superagent-files

SuperAgent Files

Define agents declaratively using .superagent YAML files -- configure model, servers, memory, sandbox, and cross-agent references in a single file.

Quick Example

# analyst.superagent
version: "1.0"

agent:
  model: "openai:gpt-5-mini"
  instructions: "You are a data analyst. Use available tools to answer questions."
  trace: true

servers:
  database:
    type: http
    url: "http://localhost:9000/mcp"
    headers:
      Authorization: "Bearer ${DB_TOKEN}"

Load and run it in Python:

import asyncio
from promptise import build_agent
from promptise.superagent import load_superagent_file

async def main():
    loader, cross_agents = load_superagent_file("analyst.superagent")
    config = loader.to_agent_config()
    agent = await build_agent(**config.to_build_kwargs())

    result = await agent.ainvoke({
        "messages": [{"role": "user", "content": "Show me top 10 customers by revenue"}]
    })
    print(result["messages"][-1].content)
    await agent.shutdown()

asyncio.run(main())

Concepts

A .superagent file is a YAML document validated against SuperAgentSchema. It replaces the programmatic build_agent() call with a declarative configuration file that can be version-controlled, shared across teams, and loaded at runtime.

The loader pipeline works in three steps:

1. Parse and validate -- SuperAgentLoader.from_file() reads YAML and validates it against the Pydantic schema. Invalid fields are rejected immediately.
2. Resolve environment variables -- resolve_env_vars() replaces ${VAR} and ${VAR:-default} placeholders with actual values from the environment.
3. Convert to native types -- to_agent_config() produces a SuperAgentConfig object whose to_build_kwargs() method returns a dict ready for build_agent(**kwargs).

Full YAML Schema

Here is a .superagent file using every available section:

version: "1.0"

agent:
  model: "openai:gpt-5-mini"          # or detailed config (see below)
  instructions: "You are a research assistant."
  trace: true

identity:
  provider: entra                      # local|entra|aws|gcp|spiffe|oidc|auto
  agent_id: research-bot               # who is acting (for attribution)
  owner: research-team
  labels: {env: prod}
  client_id: "${AZURE_CLIENT_ID}"      # provider-specific (Entra here)
  resource: api://search.example.com   # audience the credential targets

servers:
  search:
    type: http
    url: "https://search.example.com/mcp"
    transport: streamable-http
    headers:
      Authorization: "Bearer ${SEARCH_TOKEN}"
  local_tools:
    type: stdio
    command: python
    args: ["-m", "my_tools.server"]
    env:
      API_KEY: "${MY_API_KEY}"
    cwd: "/opt/tools"
    keep_alive: true

cross_agents:
  math_expert:
    file: "./agents/math.superagent"
    description: "Specialized math and calculation agent"

memory:
  provider: chroma                     # "in_memory", "chroma", or "mem0"
  collection: research_memory
  persist_directory: ".promptise/chroma"

sandbox:
  backend: docker
  image: "python:3.11-slim"
  cpu_limit: 2
  memory_limit: "4G"
  disk_limit: "10G"
  network: restricted
  timeout: 300
  tools: ["python"]
  workdir: "/workspace"
  allow_sudo: false