Simple Agent

A simple agent is the most basic type of agent in the HasteKit SDK. It executes in-process without durability, making it perfect for stateless interactions, testing, and simple use cases that don’t require crash recovery or long-running workflows.

Overview

Simple agents provide:

System instructions: Define the agent’s behavior and personality
LLM integration: Use any supported LLM provider (OpenAI, Anthropic, Gemini, etc.)
Tool support: Optional tools for function calling
Conversation history: Optional memory across interactions
Streaming responses: A live channel of response chunks delivered through the run handle
Stop signal: Cancel an in-flight run cleanly via handle.Stop, including mid-stream and mid-tool-call
Hooks: Intercept tool calls and model calls for auth, budgets, and audit

Unlike durable agents, simple agents execute in-process and don’t persist state between runs across restarts. They’re ideal for stateless applications, quick prototypes, and scenarios where you don’t need crash recovery.

Creating a Simple Agent

To create a simple agent, use hastekit.NewAgent() with AgentConfig:

import (
    "context"
    "fmt"
    "log"

    "os"

    "github.com/hastekit/agent-sdk-go/pkg/utils"
    "github.com/hastekit/agent-sdk-go/pkg/agents"
    "github.com/hastekit/agent-sdk-go/pkg/agents/history"
    "github.com/hastekit/agent-sdk-go/pkg/gateway/llm/responses"
    hastekit "github.com/hastekit/agent-sdk-go"
)

// Configure an LLM client
client := hastekit.NewLLMClient([]hastekit.ProviderConfig{
    {
        ProviderName:  hastekit.ProviderOpenAI,
        BaseURL:       "",
        CustomHeaders: nil,
        ApiKeys: []*hastekit.APIKeyConfig{
            {
                Name:   "Key 1",
                APIKey: os.Getenv("OPENAI_API_KEY"),
            },
        },
    },
})

// Create the agent
agent := hastekit.NewAgent(&hastekit.AgentConfig{
    Name:        "Hello world agent",
    Instruction: hastekit.NewPrompt("You are helpful assistant. You greet user with a light-joke"),
    LLM:         client.Model("OpenAI/gpt-4o-mini"),
    Parameters: responses.Parameters{
        Temperature: utils.Ptr(0.2),
    },
})

AgentConfig Fields

Field	Type	Description
Name	`string`	A unique identifier for the agent
Instruction	`agents.SystemPromptProvider`	System prompt defining agent behavior (use `hastekit.NewPrompt()` for simple strings)
LLM	`llm.Provider`	The LLM provider instance (bound via `client.Model("Provider/model")`)
Parameters	`responses.Parameters`	Optional LLM parameters (temperature, max tokens, etc.)
Tools	`[]agents.Tool`	Optional array of tools the agent can use
Handoffs	`[]*agents.Handoff`	Optional sub-agents this agent can hand off to (see Handoffs)
StickyHandoff	`bool`	Keep routing a thread to the agent it was last handed off to
MaxLoops	`*int`	Optional cap on agent loop iterations (defaults to `50`)
History	`*history.CommonConversationManager`	Optional conversation history manager
Output	`map[string]any`	Optional JSON schema for structured output
McpServers	`[]agents.MCPToolset`	Optional MCP server clients
Skills	`agents.SkillProvider`	Optional folders of instructions the agent reads on demand (see Skills)
Hooks	`[]agents.Hook`	Optional interceptors for tool calls and model calls (see Hooks)

Executing an Agent

Execute() is non-blocking — it generates a stream id, subscribes to the broker, and returns an *AgentHandle. There are two valid ways to consume the handle:

handle.Result() — drains the chunk channel internally and returns the aggregated AgentOutput. Use this when you only care about the final output.
for chunk := range handle.Chunks + handle.Wait() — observe chunks as they arrive (e.g. to forward to a UI or SSE stream), then collect the aggregated output.

Call handle.Stop(ctx) at any point to stop the run — including in the middle of a streaming model call or a running tool.

handle, err := agent.Execute(context.Background(), &agents.AgentInput{
    Message: history.Message{
        Messages: []responses.InputMessageUnion{
            responses.UserMessage("Hello!"),
        },
    },
})
if err != nil {
    log.Fatal(err)
}

// One-shot: drain + aggregate.
out, err := handle.Result()
if err != nil {
    log.Fatal(err)
}
fmt.Println(out.Output[0].OfOutputMessage.Content[0].OfOutputText.Text)

Or if you want to consume chunks live:

for chunk := range handle.Chunks {
    // forward chunk to your UI / SSE / log
}
out, err := handle.Wait()

AgentInput Fields

Field	Type	Description
Message	`history.Message`	The turn to run, wrapping `[]responses.InputMessageUnion` (use `responses.UserMessage()` helper)
Namespace	`string`	Optional namespace for conversation isolation
ThreadID	`string` (json `thread_id`)	Optional ID of the thread to continue. `Execute()` generates one if empty
PreviousRunID	`string`	Optional ID of the run to continue from, to branch from an earlier turn instead of the thread’s tip
SessionID	`string` (json `shared_session_id`)	Optional conversation ID shared between a parent agent and its sub-agent
RunContext	`map[string]any`	Optional context data for template variable resolution and for hooks
StreamID	`string`	Optional broker channel id. `Execute()` generates one if empty; supply your own to resume an existing stream or coordinate a stop signal.

AgentHandle

Execute() returns a handle:

type AgentHandle struct {
    StreamID string                          // Broker channel id for this run
    Chunks   <-chan *responses.ResponseChunk // Live stream of chunks; closed on completion
}

func (h *AgentHandle) Stop(ctx context.Context) error
func (h *AgentHandle) EnqueueMessage(ctx context.Context, msg history.Message) error
func (h *AgentHandle) Wait() (*AgentOutput, error)
func (h *AgentHandle) Result() (*AgentOutput, error)

Stop records a stop request on the broker and unwinds the run — see Stopping an In-Flight Run.
EnqueueMessage pushes a message onto the run’s queue. The agent drains it at iteration boundaries, so a follow-up or an approval decision reaches a run that is still in flight. For a run that has already paused and exited, the next agent.Execute on the same thread is the right entry instead.
Wait blocks until the run finishes and returns the aggregated output. Safe to call only after Chunks has been drained.
Result drains Chunks internally and returns the aggregated output — equivalent to for range Chunks {}; Wait().

Calling Wait without draining Chunks will deadlock once the broker’s per-subscriber buffer fills, because the agent’s publisher back-pressures. Use Result if you don’t intend to consume chunks yourself.

AgentOutput Structure

handle.Wait() returns the aggregated AgentOutput:

type AgentOutput struct {
    RunID      string                        // Unique run identifier
    Status     agentstate.RunStatus          // Execution status
    Output     []responses.InputMessageUnion // Agent's response messages
    Interrupts []responses.Interrupt         // One per tool call awaiting approval (human-in-the-loop)
}

Complete Example

Here’s a complete working example:

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/hastekit/agent-sdk-go/pkg/agents"
	"github.com/hastekit/agent-sdk-go/pkg/agents/history"
	"github.com/hastekit/agent-sdk-go/pkg/gateway/llm/responses"
	hastekit "github.com/hastekit/agent-sdk-go"
	"github.com/hastekit/agent-sdk-go/pkg/utils"
)

func main() {
	// Configure an LLM client
	client := hastekit.NewLLMClient([]hastekit.ProviderConfig{
		{
			ProviderName:  hastekit.ProviderOpenAI,
			BaseURL:       "",
			CustomHeaders: nil,
			ApiKeys: []*hastekit.APIKeyConfig{
				{
					Name:   "Key 1",
					APIKey: os.Getenv("OPENAI_API_KEY"),
				},
			},
		},
	})

	// Create agent
	agent := hastekit.NewAgent(&hastekit.AgentConfig{
		Name:        "Hello world agent",
		Instruction: hastekit.NewPrompt("You are helpful assistant. You greet user with a light-joke"),
		LLM:         client.Model("OpenAI/gpt-4o-mini"),
		Parameters: responses.Parameters{
			Temperature: utils.Ptr(0.2),
		},
	})

	// Execute agent
	handle, err := agent.Execute(context.Background(), &agents.AgentInput{
		Message: history.Message{
            Messages: []responses.InputMessageUnion{
			    responses.UserMessage("Hello!"),
            },
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	out, err := handle.Result()
	if err != nil {
		log.Fatal(err)
	}

	// Print response
	fmt.Println(out.Output[0].OfOutputMessage.Content[0].OfOutputText.Text)
}

Streaming Responses

Streaming is built into the handle — every run delivers chunks on handle.Chunks as they arrive:

handle, err := agent.Execute(context.Background(), &agents.AgentInput{
    Message: history.Message{
        Messages: []responses.InputMessageUnion{
            responses.UserMessage("Tell me a story"),
        },
    },
})
if err != nil {
    log.Fatal(err)
}

for chunk := range handle.Chunks {
    switch chunk.ChunkType() {
    case "response.output_text.delta":
        if chunk.OfOutputTextDelta != nil {
            fmt.Print(chunk.OfOutputTextDelta.Delta)
        }
    case "response.output_text.done":
        if chunk.OfOutputTextDone != nil && chunk.OfOutputTextDone.Text != nil {
            fmt.Printf("\n\nComplete text: %s\n", *chunk.OfOutputTextDone.Text)
        }
    }
}

out, _ := handle.Wait()
_ = out

Stopping an In-Flight Run

handle.Stop(ctx) records a stop request on the broker. The run records a "Cancelled by user" assistant turn in history and emits run.completed cleanly — the chunk stream stays open while the agent winds down, so you’ll still see that final chunk before the channel closes.

go func() {
    time.Sleep(2 * time.Second)
    _ = handle.Stop(context.Background())
}()

for chunk := range handle.Chunks {
    _ = chunk
}

Stop does not wait for an iteration boundary. It reaches work already in flight:

Mid-stream — the model call is cut off where it is, rather than waited out. Text that had already streamed still reached the client, but the turn is recorded as cancelled rather than as a half-answer the model never finished. Cancelling also reaches the provider’s own request, which is what actually stops the tokens being generated and billed.
Mid-tool-call — a running tool has its context cancelled. A tool that ignores cancellation is abandoned after a grace period (agents.DefaultCancelGrace, 2s) so the run still ends; it keeps running in the background, unobserved.

Either way the loop’s invariant holds: every function_call in history is answered — a cancelled call gets a synthetic result saying so — so a stopped thread is still a valid thread to resume from.

Reaching a running tool or an in-flight stream needs a broker implementing agents.StopWatcher; the built-in memory and Redis brokers both do. With a plain broker the stop still lands, at the loop’s next iteration boundary.

Single-Turn Execution

SingleTurn ends the run as soon as the model has responded, before any tool is executed. The AgentOutput carries exactly what the model emitted — assistant text and/or tool calls — with status completed. This is for evaluating a single decision rather than an outcome: offline single-turn evals score “given this conversation, what does the model do next?”, where executing the tool (or faking its result) would replace the thing under test with an improvised continuation. It lives on agents.AgentOptions rather than AgentConfig, so set it with an AgentOption:

agent := hastekit.NewAgent(
    &hastekit.AgentConfig{
        Name:        "Evaluated agent",
        Instruction: hastekit.NewPrompt("You are a helpful assistant."),
        LLM:         model,
        Tools:       []hastekit.Tool{weatherTool},
    },
    func(o *agents.AgentOptions) { o.SingleTurn = true },
)

This is not the same as MaxLoops: 1, which still executes the first round of tools and then fails the run with “exceeded maximum loops”.

Helper Functions

The SDK provides convenient helper functions for creating messages:

responses.UserMessage(msg string): Creates a user message from a string

Next Steps

Learn about system instructions for customizing agent behavior
Add conversation history for context-aware interactions
Integrate tools to extend agent capabilities
Give the agent skills it reads only when it needs them
Add hooks for auth, budgets, and audit
Explore durable agents for production workloads

Getting started

LLM Gateway

Agents

Workflows

Overview

Creating a Simple Agent

AgentConfig Fields

Executing an Agent

AgentInput Fields

AgentHandle

AgentOutput Structure

Complete Example

Streaming Responses

Stopping an In-Flight Run

Single-Turn Execution

Helper Functions

Next Steps

​Overview

​Creating a Simple Agent

​AgentConfig Fields

​Executing an Agent

​AgentInput Fields

​AgentHandle

​AgentOutput Structure

​Complete Example

​Streaming Responses

​Stopping an In-Flight Run

​Single-Turn Execution

​Helper Functions

​Next Steps

Overview

Creating a Simple Agent

AgentConfig Fields

Executing an Agent

AgentInput Fields

AgentHandle

AgentOutput Structure

Complete Example

Streaming Responses

Stopping an In-Flight Run

Single-Turn Execution

Helper Functions

Next Steps