Agent

Gestalt agent providers are global backends that own canonical agent state: sessions, turns, interactions, and turn events. Callers create a session, submit turns into that session, then inspect or stream the resulting turn state through the shared Gestalt HTTP API, CLI, or SDKs.

Agent providers are global, not plugin-scoped. A session either selects a named providers.agent entry explicitly or inherits the sole/default provider when it omits provider.

Mental model

Use an agent provider when you want one portable interface for:

multi-turn sessions
asynchronous turns
tool execution through Gestalt plugin operations
provider-owned approvals, clarifications, and other interactions
stored event history for rendering or replay

This is intentionally different from runtime, which decides where executable providers run, and from workflow, which decides when a target runs.

Configuring `providers.agent`


providers:
  indexeddb:
    main:
      source: ./providers/indexeddb/relationaldb/manifest.yaml
      config:
        dsn: sqlite:///tmp/gestalt.db
 
  agent:
    simple:
      source: ./providers/agent/simple/manifest.yaml
      default: true
      indexeddb:
        provider: main
        db: simple_agent
      config:
        runStore: runs
        idempotencyStore: run_idempotency
        defaultModel: fast
        aliases:
          fast: openai/gpt-4.1-mini
          deep: anthropic/claude-sonnet-4-20250514
        maxSteps: 8
        timeoutSeconds: 120

If exactly one agent provider is configured, or one is marked default: true, session creation may omit provider.

If an agent provider needs durable state, configure indexeddb on that provider entry. Gestalt exposes the selected store to the provider process as the standard SDK GESTALT_INDEXEDDB_SOCKET, but the provider still owns the canonical session, turn, interaction, and event records stored there.

If you want the provider to run in a hosted sandbox instead of directly on the gestaltd host, add execution.mode: hosted and execution.runtime to that same providers.agent.<name> entry:


providers:
  agent:
    simple:
      source: ./providers/agent/simple/manifest.yaml
      execution:
        mode: hosted
        runtime:
          provider: modal
          image: ghcr.io/valon/gestalt-python-runtime:latest
          pool:
            minReadyInstances: 1
            maxReadyInstances: 4
            startupTimeout: 2m
            healthCheckInterval: 30s
            restartPolicy: always
            drainTimeout: 1m
      egress:
        allowedHosts:
          - api.openai.com
          - api.anthropic.com
      config:
        defaultModel: fast

This keeps the caller interface the same. The request still targets provider: simple. The only difference is where the provider executes and how gestaltd enforces host-service access and egress.

execution.runtime.pool is the hosted agent lifecycle block.

Session and turn shape

The caller-facing contract is split into two steps:

Create or look up a session.
Create turns inside that session.

Example session request:


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

Example turn request:


{
  "model": "fast",
  "messages": [
    {
      "role": "user",
      "text": "Summarize the roadmap risk."
    }
  ],
  "toolRefs": [
    {
      "pluginName": "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 you need explicit-only tools.

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

Providers may also advertise capabilities such as:


{
  "streamingText": true,
  "toolCalls": true,
  "parallelToolCalls": false,
  "structuredOutput": true,
  "interactions": true,
  "resumableTurns": true
}

First-party provider

The current first-party provider is agent/simple from valon-technologies/gestalt-providers. It is intentionally small:

text-in, text-out agent loop
OpenAI and Anthropic model backends
Gestalt plugin operations as tools
provider-owned IndexedDB persistence
asynchronous turns plus turn event history