Agent

In the current public Go SDK, an embedded agent is defined by runtime defaults plus prompt shaping plus session overrides. This page shows the clean patterns for building named agent roles in your own product without inventing an abstraction the SDK does not actually require.

The Public SDK Model

The Go SDK does not force you through a heavyweight exported Agent type before you can run anything. The real integration surface is more direct: configure a sdk.Client, then create sessions and shape role behavior through prompt and runtime overrides.

App Layer

Your agent catalog

Your product defines named roles, tenancy, policies, and reusable persona presets.

What your app owns

Runtime Layer

sdk.Client defaults

Model, working directory, permissions, memory, tools, and the base persona live on the client.

What the shared runtime owns

Session Layer

Per-run role override

A session can replace the persona, append mission context, and even switch the working directory for one run.

How one client creates many agents

Execution Layer

Mono-run execution

The resulting agent still executes through one governed runtime: prompt, tool surface, permissions, memory, and provider path stay coherent.

What actually runs

Embedded Agent Pattern

In the current public SDK, an agent is a persona plus runtime policy plus session context

There is no single exported Agent object that you must construct first. The public boundary is simpler and more composable: define a base runtime, then shape role behavior through prompt and session overrides.

Model Boundary

Different roles, same client

Use session overrides when the model, tools, and runtime policy can stay shared but the persona or task context changes.

Client Pool Pattern

Different model, different client

If one role should use a different provider, default permission policy, or root path, build a dedicated client for that role instead of fighting session-level state.

Base Persona At Client Level

Use ClientConfig.SystemPromptTemplate when one runtime instance is fundamentally one role. This is the right pattern for a review runtime, a support runtime, a repository migration runtime, or a research runtime.

Client-level persona

client, err := sdk.NewClient(&sdk.ClientConfig{
    Model: sdk.ModelIdentifier{
        Provider: sdk.APIProviderAnthropic,
        Model:    "claude-sonnet-4-20250514",
    },
    APIKey:         os.Getenv("ANTHROPIC_API_KEY"),
    WorkingDir:     "/workspace/acme-backend",
    PermissionMode: sdk.PermissionModeOnRequest,
    SystemPromptTemplate: `You are Acme's backend engineering agent.

Your priorities:
- Make minimal, correct changes.
- Prefer existing project conventions.
- Explain tradeoffs when there is real ambiguity.
- Do not invent APIs or behavior.`,
})

Role Variation At Session Level

The better scaling pattern for multi-role applications is one shared client and many sessions. Each session can change persona and assignment context without rebuilding the provider, tool registry, memory system, or permission engine from scratch.

Role-specific session

session, err := client.CreateSession(ctx)
if err != nil {
    log.Fatal(err)
}
defer session.Close()

session.SetSystemPromptTemplate(`You are Mira, a code review agent.
- Prioritize correctness, regressions, and missing tests.
- Keep summaries short and concrete.`)

session.SetAppendSystemPrompt(`Repository policy:
- Findings first.
- No patching unless the caller explicitly asks.`)

resp, err := session.SubmitMessage(ctx, "Review the recent authentication refactor.")
if err != nil {
    log.Fatal(err)
}

fmt.Println(resp.TotalTokens)

Practical Rule

If only the role or mission changes, keep one shared client. If the model, root path, or default permission policy changes materially, create a dedicated client for that role.

Agent Parameters In Practice

These are the surfaces that actually define an embedded agent today. This table is intentionally practical: it focuses on the parameters and methods that change behavior for Go SDK integrations.

API surface	Scope	Purpose	Runtime effect	Notes
ClientConfig.Model	client	Chooses the default reasoning provider and model for that embedded runtime.	All sessions opened from the client inherit the same model path.	There is no public session-level model override in the current SDK surface.
ClientConfig.PermissionMode	client	Defines how the agent gets approval for risky actions.	Changes the operational behavior of every session created by that client.	This is part of agent behavior even though it is runtime policy rather than prompt text.
ClientConfig.WorkingDir	client	Defines the repository or workspace root the agent operates from.	Affects runtime context, project instructions discovery, and tool execution paths.	Use different clients when roles should live in different roots by default.
ClientConfig.SystemPromptTemplate	client	Defines the base persona and standing instructions for the embedded agent.	Becomes the default system prompt template for every session unless overridden.	Best fit for one-role runtimes such as review agent, research agent, or support agent.
PromptConfig.AppendSystemPrompt	client	Adds stable business or domain context on top of the base persona.	Appends shared organization rules every turn without replacing the core persona.	Use for company policy, product constraints, or compliance context.
PromptConfig.ToolHints	client	Biases how the agent should use selected tools.	Appends extra provider-facing guidance to chosen tool descriptions.	This shapes behavior without forcing a full prompt rewrite.
Session.SetSystemPromptTemplate	session	Replaces the base persona for one run.	Lets one shared client create many different role-specific agents.	Passing an empty string clears the session override.
Session.SetAppendSystemPrompt	session	Attaches run-specific assignment context or constraints.	Keeps the role the same while changing the mission context for one session.	Use this for release window details, tenant context, or task-specific rules.
Session.SetWorkingDirectory	session	Moves one agent session into a different workspace root.	Updates runtime context, file tools, and project-instruction lookup for that run.	Useful when the same app-level role operates across multiple repositories.

Own Your Agent Catalog In App Code

Your product should usually own its role catalog instead of waiting for the runtime to expose one perfect universal type. Keep a thin preset struct on your side and translate it into session overrides when a run starts.

Agent preset helper

type AgentPreset struct {
    Name         string
    Role         string
    Persona      string
    Context      string
}

func NewAgentSession(ctx context.Context, client *sdk.Client, preset AgentPreset) (*sdk.Session, error) {
    session, err := client.CreateSession(ctx)
    if err != nil {
        return nil, err
    }

    session.SetSystemPromptTemplate(fmt.Sprintf(
        "You are %s, a %s.

%s",
        preset.Name,
        preset.Role,
        preset.Persona,
    ))

    if preset.Context != "" {
        session.SetAppendSystemPrompt(preset.Context)
    }

    return session, nil
}

When To Use A Client Pool

There is no public session-level model switch in the current SDK. If one role should use a different provider or a cheaper local model while another role uses a premium reasoning model, model separation belongs at the client layer.

Role-specific client pool

reviewClient, _ := sdk.NewClient(&sdk.ClientConfig{
    Model: sdk.ModelIdentifier{Provider: sdk.APIProviderAnthropic, Model: "claude-sonnet-4-20250514"},
    APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    SystemPromptTemplate: "You are the code review runtime.",
})

researchClient, _ := sdk.NewClient(&sdk.ClientConfig{
    Model: sdk.ModelIdentifier{Provider: sdk.APIProviderOpenAI, Model: "gpt-5.5"},
    APIKey: os.Getenv("OPENAI_API_KEY"),
    SystemPromptTemplate: "You are the research runtime.",
})

1Shared client

Best when only persona or mission context changes.

2Client pool

Best when provider, model, or default runtime policy differs by role.

3Team runtime

Persistent mailbox-based profiles are the deeper runtime level, not the first embedding API.

Internal Team-Agent Model Behind The Scenes

The repository already contains a richer persistent team model built around AgentProfile, mailboxes, and dispatching. It matters conceptually because it shows the long-term direction, but it is not the main public Go SDK contract for embedded product developers today.

Field	Type	Meaning	Status for Go SDK users
ID	string	Stable UUID for a persistent team member identity.	Internal runtime concept today, not the primary public Go SDK integration surface.
Nickname	string	Human-facing name injected into the persona prompt.	Useful for understanding the long-term team runtime direction.
Role	string	Routing tag such as researcher, engineer, or manager.	Used by dispatcher and mailbox-based team coordination internally.
TeamID	string	Associates the profile with a named persistent team.	Concept/runtime-level field, not a top-level Go SDK app setting yet.
SystemPromptTemplate	string	Base persona template for that persistent team member.	This is conceptually aligned with SDK persona shaping, but not exposed as the same public type.
Model	string	Preferred model in provider:model format.	Internal profile preference; embedded SDK apps currently handle this with separate clients or client pools.
Skills	[]string	Preloaded skill names attached to the persistent profile.	Runtime-team feature direction rather than a first-class public SDK persona field.
Metadata	map[string]string	Extension attributes for domain-specific behavior.	Internal extensibility point for future richer team profiles.

Continue with Prompt for the full prompt architecture and override matrix, Providers & Auth for model wiring, or Agent Teams and Mailboxes for the persistent team runtime level.