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": [
    {
      "appName": "roadmap",
      "operation": "sync"
    }
  ],
  "responseSchema": {
    "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.

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"
 
    gestalt "github.com/valon-technologies/gestalt/sdk/go"
)
 
func summarize(ctx context.Context, req gestalt.Request) (string, error) {
    agents, err := req.Agent()
    if err != nil {
        return "", err
    }
    defer agents.Close()
 
    session, err := agents.CreateSession(ctx, gestalt.AgentCreateSession{
        ClientRef: "roadmap-risk",
    })
    if err != nil {
        return "", err
    }
 
    turn, err := agents.CreateTurn(ctx, gestalt.AgentCreateTurn{
        SessionID: session.GetId(),
        Messages: []gestalt.AgentMessage{{
            Role: "user",
            Text: "Summarize the latest roadmap risk.",
        }},
    })
    if err != nil {
        return "", err
    }
    return turn.GetId(), nil
}

Python


from gestalt import AgentCreateSession, AgentCreateTurn
from gestalt import AgentMessage, Request
 
def summarize(request: Request) -> str:
    with request.agent() as agents:
        session = agents.create_session(
            AgentCreateSession(client_ref="roadmap-risk")
        )
        turn = agents.create_turn(
            AgentCreateTurn(
                session_id=session.id,
                messages=[
                    AgentMessage(
                        role="user",
                        text="Summarize the latest roadmap risk.",
                    )
                ],
            )
        )
        return turn.id

Rust


use gestalt::{
    AgentCreateSession, AgentCreateTurn,
    AgentMessage, Request,
};
 
async fn summarize(req: &Request) -> Result<String, Box<dyn std::error::Error>> {
    let mut agents = req.agent().await?;
    let session = agents.create_session(AgentCreateSession {
        client_ref: "roadmap-risk".into(),
        ..Default::default()
    }).await?;
 
    let turn = agents.create_turn(AgentCreateTurn {
        session_id: session.id,
        messages: vec![AgentMessage {
            role: "user".into(),
            text: "Summarize the latest roadmap risk.".into(),
            ..Default::default()
        }],
        ..Default::default()
    }).await?;
 
    Ok(turn.id)
}

TypeScript


import { Agent, type Request } from "@valon-technologies/gestalt";
 
export async function summarize(request: Request) {
  const agents = new Agent(request);
  const session = await agents.createSession({
    clientRef: "roadmap-risk",
  });
  const turn = await agents.createTurn({
    sessionId: session.id,
    messages: [
      {
        role: "user",
        text: "Summarize the latest roadmap risk.",
      },
    ],
  });
  return turn.id;
}

Agent workflow steps

Workflow schedules and triggers can include agent turns directly as target.steps[].agent:


workflows:
  eventTriggers:
    summarize_roadmap_item:
      provider: local
      match:
        type: roadmap.item.updated
        source: roadmap
        subject: item
      target:
        steps:
          - id: summarize
            agent:
              provider: simple
              model: fast
              prompt: "Summarize the updated roadmap item."
              tools:
                - app: roadmap
                  operation: items.get
      invokes:
        - app: roadmap
          operation: items.get

For user-owned triggers, pass the full target object to the workflow CLI:


gestalt workflow triggers create \
  --provider local \
  --type roadmap.item.updated \
  --source roadmap \
  --subject item \
  --target-file - <<'JSON'
{
  "steps": [
    {
      "id": "summarize",
      "agent": {
        "provider": "simple",
        "model": "fast",
        "prompt": "Summarize the updated roadmap item.",
        "tools": [
          {
            "app": "roadmap",
            "operation": "items.get"
          }
        ]
      }
    }
  ]
}
JSON
 
gestalt workflow events publish \
  --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 the provider decides how to expose those tools to the model. Use the SDK AgentHost helpers to list authorized tools, execute selected tools, and resolve configured model connections.

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. 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.