Agents and execution

An agent repeatedly calls its model, executes selected tools, and supplies their results to the next model call. A run ends when the agent answers, pauses for input, fails, or reaches its loop limit.

Configure the agent

With model obtained from client.Model(...):

agent, err := hastekit.NewAgent(&hastekit.AgentConfig{
    Name: "assistant",
    LLM: model,
    Instruction: hastekit.NewPrompt("Answer clearly and use tools when needed."),
})
if err != nil { return err }

LLM is the configured provider and Instruction is a prompt provider; use NewPrompt for a string. Description tells other agents what this agent does when it appears in a sub-agent catalog. Add Tools for Go functions, MCPClient for external tools, SkillClient for instruction libraries, and SubAgents for delegation. Middlewares wraps model/tool calls, prompts, and persistence. Multi-agent patterns explains how these agents compose.

Choose an execution method

Method	Returns	Cancelling its context
`agent.Run(ctx, input)`	Final result and error	Cancels local work and signals remote work through the broker
`agent.Execute(ctx, input)`	A handle with events and completion methods	Disconnects the event subscription; execution continues
`handle.Wait(ctx)`	Final result and error	Stops waiting only
`handle.Stop(ctx)`	Error from the stop request	Its context bounds the stop request

Use Run when you only need the final answer. Use Execute when the application consumes streaming events. There are no separate Start or Stream methods.

Wait for the result

Inside a function with ctx and agent:

result, err := agent.Run(ctx, &hastekit.Input{
    Namespace: "default",
    ThreadID: "support-42",
    Message: hastekit.UserTurn("Summarize the open issues."),
})
if err != nil { return err }
fmt.Println(result.Text())

Inspect result.Status and result.Interrupts as well as Text(): a successful call can return a paused run rather than a final answer. Output contains the full typed message list, including non-text output.

Consume events

handle, err := agent.Execute(ctx, &hastekit.Input{
    Namespace: "default",
    ThreadID: "support-42",
    Message: hastekit.UserTurn("Summarize the open issues."),
})
if err != nil { return err }
for chunk := range handle.Chunks {
    if chunk.OfOutputTextDelta != nil {
        fmt.Print(chunk.OfOutputTextDelta.Delta)
    }
}
result, err := handle.Wait(ctx)
if err != nil { return err }
fmt.Println(result.Status)

Always inspect the error from Wait, even after the event channel closes. One consumer should read Chunks. The handle has a bounded backlog of 256 events; if the consumer falls behind, Wait reports ErrStreamOverflow alongside any final result. The missing events cannot be reconstructed from that handle. For a synchronous caller, avoid creating a streaming handle just to call Wait; Run does not subscribe to events.

Stop a run

Call handle.Stop(ctx) or agent.Stop(ctx, streamID) with a live request context. Then wait for completion. handle.Cancel is an alias for Stop. Stopping is cooperative. Built-in memory and Redis brokers support cancellation of active model and tool calls. Custom tools must honor their context. A tool that ignores cancellation may continue running after the agent stops waiting for it; stop is not a rollback of external side effects.

Identify a run

Input field	Purpose
`Namespace`	Partition application history and run state; set it from trusted identity
`ThreadID`	Conversation thread; supply it when you need to continue the conversation
`RunID`	Optional identifier for the new run; generated when omitted
`PreviousRunID`	History branch point or the paused run being resumed
`StreamID`	Broker channel; normally generated by the SDK
`SessionID`	Shared session identity, including attachment scope for related agents
`GroupID`	Group for a new conversation; empty selects `default`
`ParentThreadID`, `Hidden`	Parent and visibility for a newly created internal thread
`Skills`, `MCP`	Per-run selections for the configured catalogs
`ClientTools`	Definitions of tools the client executes
`RunContext`	Application data supplied to prompts, tools, and middleware

ThreadID, StreamID, and the incoming message ID are generated when omitted. The final result exposes RunID; choose a stable thread ID before calling if you need it afterwards. Persistence saves increments under the same run ID. Choosing a run ID does not by itself make repeated application submissions or tool side effects idempotent.

Bound work

AgentConfig.MaxLoops defaults to 50. It limits the agent’s model loop, not tokens, elapsed time, or cost. Use model output limits and request deadlines separately. The lower-level agents.AgentOptions.SingleTurn is intended for evaluating a single model decision: it returns the model output without executing its tools. It is not exposed as a field on the root AgentConfig, and differs from MaxLoops: 1, which still executes the first round of tools.

Getting started

Core concepts

Models and providers

Tools and capabilities

Multi-agent patterns

Interfaces

Durable execution

Scheduled work

Workflows

Testing and operations

Agents and execution

Configure the agent

Choose an execution method

Wait for the result

Consume events

Stop a run

Identify a run

Bound work

​Configure the agent

​Choose an execution method

​Wait for the result

​Consume events

​Stop a run

​Identify a run

​Bound work

Configure the agent

Choose an execution method

Wait for the result

Consume events

Stop a run

Identify a run

Bound work