Agent

Agents are under active development and are not yet stable. Breaking changes may happen between releases without warning. Feedback and bug reports are welcome via GitHub Issues .

Gestalt agent providers expose one portable session-and-turn interface for agent backends such as Claude Code, Codex, Cursor, or custom harnesses.

Configuring `providers.agent`

Configure agent providers under providers.agent:


providers:
  agent:
    simple:
      source: ./providers/agent/simple/manifest.yaml
      default: true
      config:
        defaultModel: fast
        aliases:
          fast: openai/gpt-4.1-mini
          deep: openai/gpt-5.5
        maxSteps: 8
        timeoutSeconds: 120

The config block is provider-specific. If the provider stores sessions, turns, memory, or other durable records, bind it to an IndexedDB provider:


providers:
  indexeddb:
    main:
      source: ./providers/indexeddb/relationaldb/manifest.yaml
      config:
        dsn: sqlite:///tmp/gestalt.db
 
  agent:
    simple:
      source: ./providers/agent/simple/manifest.yaml
      indexeddb:
        provider: main
        db: simple_agent

For the full config shape, see Config File.

Session start hooks

Use session start hooks for lightweight provider-owned setup that should run once when a session is created:


providers:
  agent:
    claude:
      source: ./providers/agent/claude/manifest.yaml
      lifecycle:
        sessionStart:
          - id: load-memory
            type: command
            command: ["bash", "-lc", "./scripts/load-agent-context.sh"]
            cwd: ./agent-context
            timeout: 10s

Hooks fail session creation when the command fails or times out.

Workspaces and runtimes

Session callers can ask Gestalt to prepare Git checkouts before the agent session starts:


{
  "provider": "claude",
  "model": "sonnet",
  "clientRef": "repo-investigation",
  "workspace": {
    "checkouts": [
      {
        "url": "https://github.com/valon-technologies/gestalt.git",
        "ref": "main",
        "path": "gestalt"
      }
    ],
    "cwd": "gestalt"
  }
}

Use workspace for checkout and working-directory setup. Use sessionStart hooks for extra context setup.

By default, agent providers run beside gestaltd. To run an agent provider in a hosted sandbox, attach a runtime provider to the same agent entry:


providers:
  agent:
    simple:
      source: ./providers/agent/simple/manifest.yaml
      runtime:
        provider: kubernetes
        image: ghcr.io/valon/gestalt-python-runtime:latest

For runtime placement, workspace preparation, pools, and egress controls, see Runtime.

Session and turn shape

Create a session:


{
  "provider": "simple",
  "model": "fast",
  "clientRef": "roadmap-risk"
}

Create a turn inside that session:


{
  "model": "fast",
  "messages": [
    {
      "role": "user",
      "text": "Summarize the roadmap risk."
    }
  ],
  "toolRefs": [
    {
      "app": "roadmap",
      "operation": "sync"
    }
  ],
  "output": {
    "structured": {
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" }
        },
        "required": ["summary"]
      }
    }
  }
}

For user-created turns, omitting toolRefs lets Gestalt attach the caller’s authorized safe tools by default. Add toolRefs to extend that set, or set toolSource: "explicit" when the turn should only receive explicit tools.

Each messages[] entry accepts role, optional text, optional parts, and optional metadata. parts[] supports type: text | json | tool_call | tool_result | image_ref.

Turn timeouts (optional)

timeoutSeconds is an optional positive execution budget for a provider-owned turn. When omitted or zero, the provider chooses its own execution timeout, usually by delegating to the upstream model SDK default. The field does not extend the CreateTurn HTTP or RPC deadline: CreateTurn still returns quickly while model and tool work continues in the background.

You can set the budget on these surfaces:

HTTP/JSON: timeoutSeconds on POST /api/v1/agent/sessions/{sessionID}/turns
SDK: TimeoutSeconds (Go), timeout_seconds (Python), timeout_seconds (Rust), or timeoutSeconds (TypeScript) on the create-turn request
CLI: --timeout-seconds on gestalt agent, gestalt agent resume, and gestalt agent turns create for server-backed sessions (--cloud). Local gestalt agent does not accept --timeout-seconds; use --cloud when you need an explicit turn budget from the CLI.
Workflow steps: optional per-step timeout in YAML (for example 120s) or timeoutSeconds in programmatic targets. See Workflow and Config File — workflows.

timeoutSeconds under providers.agent.<name>.config in the example above is provider-specific configuration passed into the agent provider, not the Gestalt turn API field on CreateTurn.


{
  "model": "fast",
  "timeoutSeconds": 120,
  "messages": [{ "role": "user", "text": "Summarize the roadmap risk." }],
  "output": { "text": {} }
}

Invoking agents

Use gestalt agent for an interactive session:


gestalt agent
gestalt agent resume <session-id>

Use the session and turn subcommands for automation:


gestalt agent sessions create
gestalt agent sessions list --state active
gestalt agent sessions get <session-id>
gestalt agent sessions update <session-id> --state archived
 
gestalt agent turns create <session-id> \
  --message "Summarize the latest roadmap risk."
gestalt agent turns list <session-id> --status succeeded
gestalt agent turns get <turn-id>
gestalt agent turns transcript <turn-id>
gestalt agent turns cancel <turn-id> --reason "operator requested"
gestalt agent turns events list <turn-id> --after 0 --limit 100
gestalt agent turns events stream <turn-id> --after 100

For structured input, pipe JSON into --input -:


cat <<'JSON' | gestalt --format json agent turns create <session-id> --input -
{
  "model": "fast",
  "messages": [
    {
      "role": "user",
      "text": "Summarize the latest roadmap risk."
    }
  ],
  "toolRefs": [
    {
      "appName": "roadmap",
      "operation": "sync"
    }
  ]
}
JSON

Provider code can invoke agents through the SDK Agent capability:

Go


import (
    "context"
 
    "github.com/valon-technologies/gestalt/sdk/go/client"
)
 
func summarize(ctx context.Context) (string, error) {
    agents, err := client.ConnectAgent(ctx, "")
    if err != nil {
        return "", err
    }
 
    session, err := agents.CreateSession(
        ctx, "simple", "session-roadmap-risk-1", "fast",
        &client.AgentCreateSessionOptions{ClientRef: "roadmap-risk"},
    )
    if err != nil {
        return "", err
    }
 
    turn, err := agents.CreateTurn(
        ctx, session.Id, "turn-roadmap-risk-1", "fast",
        []*client.AgentMessage{{
            Role: "user",
            Text: "Summarize the latest roadmap risk.",
        }},
        nil,
    )
    if err != nil {
        return "", err
    }
    return turn.Id, nil
}

Python


from gestalt import AgentMessage, Request
 
def summarize(request: Request) -> str:
    agents = request.agent()
    session = agents.create_session(
        provider_name="simple",
        idempotency_key="session-roadmap-risk-1",
        model="fast",
        client_ref="roadmap-risk",
    )
    turn = agents.create_turn(
        session_id=session.id,
        idempotency_key="turn-roadmap-risk-1",
        model="fast",
        messages=[
            AgentMessage(
                role="user",
                text="Summarize the latest roadmap risk.",
            )
        ],
    )
    return turn.id

Rust


use gestalt::Agent;
use gestalt::agent::{
    AgentCreateSessionOptions, AgentCreateTurnOptions, AgentMessage,
};
 
async fn summarize() -> Result<String, Box<dyn std::error::Error>> {
    let mut agents = Agent::connect().await?;
    let session = agents
        .create_session(
            "session-roadmap-risk-1".into(),
            "fast".into(),
            AgentCreateSessionOptions {
                provider_name: "simple".into(),
                client_ref: "roadmap-risk".into(),
                ..Default::default()
            },
        )
        .await?;
 
    let turn = agents
        .create_turn(
            session.id,
            "turn-roadmap-risk-1".into(),
            "fast".into(),
            vec![AgentMessage {
                role: "user".into(),
                text: "Summarize the latest roadmap risk.".into(),
                ..Default::default()
            }],
            AgentCreateTurnOptions::default(),
        )
        .await?;
 
    Ok(turn.id)
}

TypeScript


import { Agent } from "@valon-technologies/gestalt";
 
export async function summarize() {
  const agents = Agent.connect();
  const session = await agents.createSession(
    "session-roadmap-risk-1",
    "fast",
    { providerName: "simple", clientRef: "roadmap-risk" },
  );
  const turn = await agents.createTurn(
    session.id,
    "turn-roadmap-risk-1",
    "fast",
    [{ role: "user", text: "Summarize the latest roadmap risk." }],
  );
  return turn.id;
}

Agent workflow steps

Workflow definitions can include agent turns directly in steps[].agent:


workflows:
  definitions:
    summarize_roadmap_item:
      provider: local
      steps:
        - id: summarize
          agent:
            provider: simple
            model: fast
            prompt: "Summarize the updated roadmap item."
            tools:
              - app: roadmap
                operation: items.get
      on:
        roadmap_item:
          event:
            type: roadmap.item.updated
            source: roadmap
            subject: item
          input:
            item: "${{ signal.data.item }}"

After the definition is applied, deliver matching events to start runs:


gestalt workflow events deliver \
  --type roadmap.item.updated \
  --source roadmap \
  --subject item \
  --data-content-type application/json \
  -p id=item-1

For workflow behavior and target shape, see Workflow.

Building your own agent provider

Manifest

An agent provider manifest declares kind: agent:


kind: agent
source: github.com/your-org/agent/example
version: 0.0.1
displayName: Example Agent
description: Minimal session-and-turn agent provider
spec:
  configSchemaPath: ./agent_config.json

Use source: ./manifest.yaml during development. For production, publish a provider release and reference it from config. For packaging and release, see Providers.

Provider interface

Agent providers implement the session, turn, interaction, and event lifecycle:

Method	Purpose
`CreateSession`	Create a provider-owned session
`GetSession`	Inspect one session
`ListSessions`	List sessions known to the provider
`UpdateSession`	Update session state, metadata, or client reference
`CreateTurn`	Persist and start a turn
`GetTurn`	Inspect one turn
`ListTurns`	List turns for a session
`CancelTurn`	Request turn cancellation
`ListTurnEvents`	Return events for a turn
`GetInteraction`	Inspect one interaction
`ListInteractions`	List interactions for a turn
`ResolveInteraction`	Apply a caller-provided interaction resolution
`GetCapabilities`	Advertise optional provider features

Providers exchange Gestalt session, turn, interaction, and event objects rather than vendor-native payloads. Return provider-owned IDs consistently; Gestalt does not rewrite them.

Capabilities and tools

Capabilities advertise optional behavior such as streaming text, tool calls, structured output, interactions, resumable turns, prepared workspaces, and MCP catalog tool support.

When a provider supports MCP catalog tools, Gestalt authorizes the caller’s tool scope and passes the resolved tool set into the turn request. The provider decides how to expose those tools to the model and uses normal host-service clients for downstream app calls.

Keep model-specific discovery, ranking, prompting, and aliases inside the provider.

Execution model

CreateTurn should persist the turn and return quickly, usually in RUNNING or PENDING. Long-running model and tool work should continue in the background. For an optional per-turn execution budget, see Turn timeouts (optional). Callers use GetTurn, ListTurnEvents, and ListInteractions to observe progress or resolve pending human input.

If your provider needs durable state, configure providers.agent.<name>.indexeddb and store canonical session and turn records there.

Turn events may include an optional display projection for CLIs and UIs. The raw event type and data remain the source of truth.