Agent SDK Go

The repository provides several specialized examples covering different providers, workflows, and patterns:

The runner resolves which model to use for every turn of an execution. The resolution logic follows this priority order:

1. Agent-specific Provider: If the agent has its own provider configured via WithModelProvider (or the alias SetModelProvider), that provider is used to resolve the model name. Note that RunConfig.Model overrides are not applied to these agents, preventing model name mismatches between providers.
2. Runner/Run Overrides: If no agent-specific provider is set, the runner checks RunConfig.Model. If set, it uses RunConfig.ModelProvider or the runner's default provider to resolve it.
3. Direct Model Instance: If the agent's model is already a model.Model instance, it is used directly.
4. Provider Default: If an agent has a provider assigned but no specific model name is set, the provider's default model is used.

This resolution occurs per turn, ensuring consistency across Run, RunSync, and RunStreaming, even after handoffs occur.

Bidirectional flow allows agents to delegate tasks to other agents and receive results back, enabling complex workflows with context management.

To enable this, you must set up mutual handoffs between the orchestrator and the worker agents.

Core Components:

• TaskID: Unique identifier for tracking tasks across agents.
• ReturnToAgent: Specifies which agent to return to after task completion.
• IsTaskComplete: Flag indicating whether the task is complete.

Example setup:

1. Create an orchestratorAgent.
2. Create a workerAgent.
3. Call orchestratorAgent.WithHandoffs(workerAgent).
4. Call workerAgent.WithHandoffs(orchestratorAgent) to allow the worker to return control to the orchestrator.

// Create specialized agents
orchestratorAgent := agent.NewAgent("Orchestrator")
orchestratorAgent.SetModelProvider(provider)
orchestratorAgent.WithModel("gpt-4")
orchestratorstrAgent.SetSystemInstructions("You coordinate tasks and analyze results.")

workerAgent := agent.NewAgent("Worker")
workerAgent.SetModelProvider(provider)
workerAgent.WithModel("gpt-3.5-turbo")
workerAgent.SetSystemInstructions("You process data and return results.")
workerAgent.WithTools(processingTool)

// Set up bidirectional handoffs
orchestratorAgent.WithHandoffs(workerAgent)
workerAgent.WithHandoffs(orchestratorAgent)  // Allow worker to return to orchestrator

// Run the orchestrator agent
result, err := runner.RunSync(orchestratorAgent, &runner.RunOptions{
    Input: "Analyze this data: [complex data]",
    MaxTurns: 10,
})

You can plug in a custom tracer at three different levels of granularity:

1. Per run: Pass a Tracer directly into TracingConfig. The runner flushes the tracer at the end of the run but does not close it (the application owns the lifecycle).
2. Per run, per agent: Provide a TracerFactory function in TracingConfig. The runner will close the tracers created by this factory when the run finishes.
3. Globally: Use tracing.SetTracerFactory to set a factory for all runs. Passing nil to this function restores the default file tracer.

// Per run
RunConfig: &runner.RunConfig{
	TracingConfig: &runner.TracingConfig{
		Tracer: myTracer,
	},
}

// Per run, per agent
RunConfig: &runner.RunConfig{
	TracingConfig: &runner.TracingConfig{
		TracerFactory: func(agentName string) (tracing.Tracer, error) {
			return newTracerFor(agentName)
		},
	},
}

// Globally
tracing.SetTracerFactory(func(agentName string) (tracing.Tracer, error) {
	return myTracerFor(agentName)
})

You can create specialized agents that collaborate by using WithHandoffs. When an agent is added via WithHandoffs, it is exposed to the model as a tool named handoff_to_<agent name>.

Key Details:

• Name Sanitization: Agent names are automatically sanitized to match Model API requirements (regex ^[a-zA-Z0-9_-]+$). For example, Weather Agent becomes handoff_to_Weather_Agent.
• Validation: Use agent.ValidateName to check names manually.
• Result Tracking: After a handoff sequence, result.LastAgent identifies the agent that produced the final output.

To implement this, define specialized agents with their own tools and instructions, then define a coordinator (frontend) agent that includes the specialized agents in its handoffs.

// Create specialized agents
mathAgent := agent.NewAgent("Math Agent")
mathAgent.SetModelProvider(provider)
mathAgent.WithModel("gemma-3-4b-it")
mathAgent.SetSystemInstructions("You are a specialized math agent.")
mathAgent.WithTools(calculatorTool)

weatherAgent := agent.NewAgent("Weather Agent")
weatherAgent.SetModelProvider(provider)
weatherAgent.WithModel("gemma-3-4b-it")
weatherAgent.SetSystemInstructions("You provide weather information.")
weatherAgent.WithTools(weatherTool)

// Create a frontend agent that coordinates tasks
frontendAgent := agent.NewAgent("Frontend Agent")
frontendAgent.SetModelProvider(provider)
frontendAgent.WithModel("gemma-3-4b-it")
frontendAgent.SetSystemInstructions(`You coordinate requests by delegating to specialized agents. 
For math calculations, delegate to the Math Agent. 
For weather information, delegate to the Weather Agent. `)
frontendAgent.WithHandoffs(mathAgent, weatherAgent)

// Run the frontend agent
result, err := runner.RunSync(frontendAgent, &runner.RunOptions{
    Input: "What is 42 divided by 6 and what's the weather in Paris?",
    MaxTurns: 20,
})