SuperAgent API Reference

SuperAgent file loader, validator, and schema definitions. Handles loading, parsing, validating, and resolving .superagent configuration files, including cross-agent reference resolution with cycle detection and environment variable substitution.

SuperAgentLoader

promptise.superagent.SuperAgentLoader

Load and parse .superagent configuration files.

This class handles the complete lifecycle of loading a .superagent file: parsing YAML, validating against schema, resolving environment variables, loading cross-agent references, and converting to native types.

Supports: - Auto-detection of file format by extension - Environment variable resolution - Cross-agent file reference resolution - Circular reference detection - Path resolution relative to config file location

Attributes:

Name	Type	Description
file_path		Resolved absolute path to the .superagent file.
schema		Parsed and validated SuperAgentSchema.
resolved_schema	SuperAgentSchema | None	Schema with environment variables resolved (after resolve_env_vars()).
cross_loaders	dict[str, SuperAgentLoader] | None	Loaders of the referenced cross-agent files (after resolve_cross_agents()), each with its own cross_loaders.

Examples:

>>> loader = SuperAgentLoader.from_file("agent.superagent")
>>> loader.resolve_env_vars()
>>> config = loader.to_agent_config()

__init__(file_path, schema, *, _loading_chain=None)

Initialize loader with parsed schema.

Parameters:

Name	Type	Description	Default
file_path	Path	Path to the source file.	required
schema	SuperAgentSchema	Validated SuperAgentSchema.	required
_loading_chain	set[Path] | None	Internal use for cycle detection in cross-agent loading.	None

from_file(file_path, *, _loading_chain=None) classmethod

Load a .superagent file from disk.

Parses YAML content and validates against SuperAgentSchema. Supports .superagent, .superagent.yaml, and .superagent.yml extensions.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to .superagent file.	required
_loading_chain	set[Path] | None	Internal use for cycle detection.	None

Returns:

Type	Description
SuperAgentLoader	SuperAgentLoader instance with parsed schema.

Raises:

Type	Description
SuperAgentError	If file not found, invalid format, or parse error.
SuperAgentValidationError	If schema validation fails.

Examples:

>>> loader = SuperAgentLoader.from_file("my_agent.superagent")
>>> # Or with explicit extension:
>>> loader = SuperAgentLoader.from_file("my_agent.superagent.yaml")

resolve_cross_agents(*, recursive=True, resolve_env=True)

Load and resolve cross-agent references.

Loads .superagent files referenced in the cross_agents section, with circular reference detection. The result is also stored in :attr:cross_loaders, and — when recursive — every loaded file's own references in its cross_loaders, so the whole team is reachable from this loader.

Parameters:

Name	Type	Description	Default
recursive	bool	If True, recursively load cross-agents of cross-agents.	True
resolve_env	bool	If True, resolve each loaded file's environment variables (raising if one is missing). promptise validate passes False to report missing variables instead.	True

Returns:

Type	Description
dict[str, SuperAgentLoader]	Mapping of cross-agent name to loaded SuperAgentLoader.

Raises:

Type	Description
SuperAgentError	If circular reference detected or file not found.

Examples:

>>> loader = SuperAgentLoader.from_file("main.superagent")
>>> cross_agents = loader.resolve_cross_agents()
>>> for name, agent_loader in cross_agents.items():
...     print(f"Loaded cross-agent: {name}")

resolve_env_vars()

Resolve all environment variables in the schema.

Replaces all ${VAR} and ${VAR:-default} references with actual values. Re-validates the schema after resolution to ensure it's still valid.

Returns:

Type	Description
SuperAgentLoader	Self (for method chaining).

Raises:

Type	Description
SuperAgentError	If required environment variables are missing.
SuperAgentValidationError	If schema is invalid after resolution.

Examples:

>>> loader = SuperAgentLoader.from_file("agent.superagent")
>>> loader.resolve_env_vars()  # Chainable
>>> # Now loader.resolved_schema contains resolved values

to_agent_config()

Convert loaded schema to agent build configuration.

Creates a SuperAgentConfig object ready to be used with build_agent().

Returns:

Type	Description
SuperAgentConfig	SuperAgentConfig ready for agent building.

Examples:

>>> loader = SuperAgentLoader.from_file("agent.superagent")
>>> loader.resolve_env_vars()
>>> config = loader.to_agent_config()
>>> # Use with: await build_agent(**config.to_build_kwargs())

to_identity()

Build the agent's :class:~promptise.identity.AgentIdentity.

Maps the resolved identity: section to the matching identity factory. Returns None when no identity: block is present. Environment variables in the section are already resolved (via :meth:resolve_env_vars) by the time this runs.

Returns:

Type	Description
AgentIdentity | None	The constructed AgentIdentity, or None.

Raises:

Type	Description
ProviderConfigError	If the identity configuration is invalid (e.g. a local identity with no agent_id).

to_model_kwargs()

Extract model kwargs from DetailedModelConfig (temperature, etc.).

Returns:

Type	Description
dict[str, Any]	Dict of model kwargs to pass to init_chat_model.
dict[str, Any]	Empty dict if model is a simple string.

to_model_string()

Convert model configuration to LangChain init string.

Converts both simple and detailed model configs to the format expected by LangChain's init_chat_model() function.

Returns:

Type	Description
str	Model string suitable for init_chat_model (e.g., "openai:gpt-4.1").

Examples:

>>> loader = SuperAgentLoader.from_file("agent.superagent")
>>> model_str = loader.to_model_string()
>>> # "openai:gpt-4.1"

to_server_specs()

Convert server configurations to ServerSpec objects.

Converts the parsed YAML server configs to Foundry's native ServerSpec types (HTTPServerSpec and StdioServerSpec).

Paths in a stdio server are relative to the file's folder, not the working directory: the server starts in the file's folder unless cwd: says otherwise (a relative cwd: is resolved against the file's folder too), and a relative command: that contains a path separator (./bin/server) is resolved against the file's folder.

Returns:

Type	Description
dict[str, ServerSpec]	Mapping of server name to ServerSpec.

Examples:

>>> loader = SuperAgentLoader.from_file("agent.superagent")
>>> loader.resolve_env_vars()
>>> servers = loader.to_server_specs()
>>> # Use with build_agent(servers=servers, ...)

validate_env_vars()

Check for missing environment variables.

Loads the nearest .env file first — the same file, with the same rule, as the promptise CLI: the working directory or a parent up to the project root, never overriding a variable that is already set, skipped when PROMPTISE_NO_DOTENV=1. Then scans the schema for ${VAR} references and checks if each variable is set in the environment. Variables with defaults (${VAR:-default}) are not reported as missing.

Returns:

Type	Description
list[str]	List of missing environment variable names (empty if all available).

Examples:

>>> loader = SuperAgentLoader.from_file("agent.superagent")
>>> missing = loader.validate_env_vars()
>>> if missing:
...     print(f"Missing: {', '.join(missing)}")

SuperAgentConfig

promptise.superagent.SuperAgentConfig

Processed configuration ready for agent building.

This class holds the final, resolved configuration that can be passed directly to build_agent().

Attributes:

Name	Type	Description
model		Model string for init_chat_model.
servers		Mapping of server name to ServerSpec.
instructions		Optional system prompt override.
trace		Enable tool tracing.
cross_agents		Cross-agent references (CrossAgentConfig), built into agents by :func:build_superagent.
max_delegation_depth		Nested-delegation limit passed to build_agent.
delegation_timeout		Default seconds to wait for a cross-agent.
include_broadcast		Add the broadcast_to_agents tool.
sandbox		Optional sandbox configuration (bool or dict).

Examples:

>>> config = SuperAgentConfig(
...     model="openai:gpt-4.1",
...     servers={"test": HTTPServerSpec(url="http://test")},
...     trace=True,
...     sandbox=True
... )

__init__(*, model, model_kwargs=None, servers, instructions=None, trace=True, identity=None, cross_agents=None, max_delegation_depth=DEFAULT_MAX_DELEGATION_DEPTH, delegation_timeout=None, include_broadcast=False, sandbox=None, memory=None, observe=None, optimize_tools=None, cache=None, approval=None, events=None, adaptive=None, guardrails=None, max_invocation_time=0)

Initialize SuperAgentConfig.

Parameters:

Name	Type	Description	Default
model	str	Model string (e.g., "openai:gpt-5-mini").	required
model_kwargs	dict[str, Any] | None	Extra kwargs for init_chat_model (temperature, etc.).	None
servers	dict[str, ServerSpec]	Mapping of server name to ServerSpec.	required
instructions	str | None	Optional system prompt.	None
trace	bool	Enable tool tracing.	True
cross_agents	dict[str, CrossAgentConfig] | None	Cross-agent references from the file.	None
max_delegation_depth	int	Nested-delegation limit.	DEFAULT_MAX_DELEGATION_DEPTH
delegation_timeout	float | None	Default seconds to wait for a cross-agent.	None
include_broadcast	bool	Add the broadcast_to_agents tool.	False
sandbox	bool | dict[str, Any] | None	Optional sandbox configuration (bool or dict).	None
memory	dict[str, Any] | None	Optional memory configuration dict.	None
observe	bool | dict[str, Any] | None	Optional observability config (bool or dict).	None
optimize_tools	bool | str | dict[str, Any] | None	Optional tool optimization (bool, str, or dict).	None
cache	bool | dict[str, Any] | None	Optional semantic cache config (bool or dict).	None

to_build_kwargs(*, cross_agents=None)

Convert to kwargs dict for build_agent().

Parameters:

Name	Type	Description	Default
cross_agents	Mapping[str, CrossAgent] | None	The built peer agents for this file's cross_agents: section. A cross-agent is an agent of its own, so it cannot be built here; :func:build_superagent builds the whole team and passes them in. When the file declares cross-agents and none are given, a UserWarning says so and the agent is built without them.	None

Returns:

Type	Description
dict[str, Any]	Dict ready to unpack: build_agent(**config.to_build_kwargs())

Examples:

>>> config = loader.to_agent_config()
>>> kwargs = config.to_build_kwargs()
>>> agent = await build_agent(**kwargs)
>>> # A file with cross_agents: build the whole team instead
>>> agent = await build_superagent("coordinator.superagent")

load_superagent_file

promptise.superagent.load_superagent_file(file_path, *, resolve_refs=True)

Convenience function to load a .superagent file with all resolutions.

Loads the file, resolves environment variables (after loading the nearest .env file, like the promptise CLI), and optionally resolves cross-agent references — at every depth — in a single call.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to .superagent file.	required
resolve_refs	bool	If True, resolve cross-agent references.	True

Returns:

Type	Description
SuperAgentLoader	Tuple of (main_loader, cross_agent_loaders). The cross-agent loaders
dict[str, SuperAgentLoader]	carry their own references in cross_loaders.

Raises:

Type	Description
SuperAgentError	If loading or validation fails.

Examples:

>>> main, cross_agents = load_superagent_file("agent.superagent")
>>> config = main.to_agent_config()
>>> # Build the agent (a file with cross_agents: use build_superagent)
>>> agent = await build_agent(**config.to_build_kwargs())

Schema Definitions

SuperAgentSchema

promptise.superagent_schema.SuperAgentSchema

Bases: BaseModel

Root schema for .superagent YAML files.

This is the top-level schema that validates the entire .superagent file structure. It supports versioning for future compatibility and ensures at least one of servers, cross_agents, or sandbox is configured.

Attributes:

Name	Type	Description
version	Literal['1.0']	Schema version. Optional; "1.0" (the only version) is the default.
agent	AgentSection	Agent-level configuration (model, instructions, trace).
servers	dict[str, ServerConfig]	Named MCP server configurations.
cross_agents	dict[str, CrossAgentConfig] | None	Optional cross-agent references.
sandbox	bool | SandboxConfigSection | None	Optional sandbox configuration (bool or detailed config).
memory	MemorySection | None	Optional memory configuration.
observability	bool | ObservabilitySection | None	Optional observability configuration (True or detailed).
optimize_tools	bool | str | ToolOptimizationSection | None	Optional tool optimization (True, string level, or detailed).

Examples:

>>> schema = SuperAgentSchema(
...     version="1.0",
...     agent=AgentSection(model="openai:gpt-5-mini"),
...     servers={"math": HTTPServerConfig(url="http://...")},
...     sandbox=True,
...     observability=True,
...     optimize_tools="semantic",
... )

validate_has_config()

Ensure at least servers, cross_agents, or sandbox is configured.

AgentSection

promptise.superagent_schema.AgentSection

Bases: BaseModel

Agent-level configuration section.

Defines the core agent configuration including model selection, system prompt, and tool tracing settings.

Attributes:

Name	Type	Description
model	ModelConfig	Model configuration (simple string or detailed object).
instructions	str | None	Optional system prompt override.
trace	bool	Enable tool invocation tracing.

Examples:

>>> agent = AgentSection(
...     model="openai:gpt-4.1",
...     instructions="You are a helpful assistant.",
...     trace=True
... )

IdentityConfig

The identity: section — gives the agent a local or verifiable Agent Identity. See the .superagent reference.

promptise.superagent_schema.IdentityConfig

Bases: BaseModel

Agent identity configuration for .superagent files.

Gives the agent a stable, traceable identity (see :mod:promptise.identity). A local identity (provider: local) needs only an agent_id and tags the agent's actions for attribution. A verifiable identity (any cloud provider, or auto) additionally mints a signed credential the agent presents to the MCP servers it calls, so they can authenticate and attribute it.

All string fields support ${ENV_VAR} resolution. Fields that do not apply to the chosen provider are ignored.

Examples:

Local (attribution only)::

identity:
  provider: local
  agent_id: billing-bot
  owner: payments
  labels: {env: prod}

Verifiable via Microsoft Entra::

identity:
  provider: entra
  agent_id: billing-bot
  client_id: ${AZURE_CLIENT_ID}
  resource: api://my-mcp-server

to_identity()

Build the :class:~promptise.identity.AgentIdentity this describes.

Dispatches to the matching identity factory by provider. Shared by every declarative surface (.superagent files and .agent runtime manifests) so identity is constructed identically everywhere.

Environment variables are expected to be already resolved on this config by the caller's loader.

Returns:

Type	Description
AgentIdentity	The constructed AgentIdentity.

Raises:

Type	Description
ProviderConfigError	If the configuration is invalid for the chosen provider (e.g. a local identity with no agent_id).

Server Configuration

ServerConfig

Discriminated union type: HTTPServerConfig | StdioServerConfig, selected by the type field ("http" or "stdio").

HTTPServerConfig

promptise.superagent_schema.HTTPServerConfig

Bases: BaseModel

HTTP/SSE MCP server configuration.

Configuration for remote MCP servers accessible via HTTP, streamable HTTP, or Server-Sent Events (SSE) transports.

Attributes:

Name	Type	Description
type	Literal['http']	Always "http" for this variant (discriminator field).
url	str	Full endpoint URL (supports ${ENV_VAR}).
transport	Literal['http', 'streamable-http', 'sse']	Transport protocol ("http", "streamable-http", "sse").
headers	dict[str, str]	Optional HTTP headers (values support ${ENV_VAR}).
bearer_token	str | None	Token sent as Authorization: Bearer <token> (supports ${ENV_VAR}).
api_key	str | None	Pre-shared key sent as x-api-key: <key> (supports ${ENV_VAR}).
audience	str | None	Resource audience for a credential minted from the agent's identity: (used when no bearer_token is set).

The old auth: field is rejected: it was never sent to the server.

Examples:

>>> server = HTTPServerConfig(
...     type="http",
...     url="http://127.0.0.1:8000/mcp",
...     api_key="${INCIDENTS_API_KEY}",
... )

reject_auth(data) classmethod

Reject auth:, which earlier versions accepted but never sent.

StdioServerConfig

promptise.superagent_schema.StdioServerConfig

Bases: BaseModel

Stdio (local process) MCP server configuration.

Configuration for local MCP servers that communicate via standard input/output, typically a subprocess launched by the agent.

Attributes:

Name	Type	Description
type	Literal['stdio']	Always "stdio" for this variant (discriminator field).
command	str	Executable command to launch.
args	list[str]	Command-line arguments.
env	dict[str, str]	Environment variables (values support ${ENV_VAR}).
cwd	str | None	Optional working directory.
keep_alive	bool	Whether to maintain persistent connection.

Examples:

>>> server = StdioServerConfig(
...     type="stdio",
...     command="python",
...     args=["-m", "mypkg.server"],
...     env={"API_KEY": "${MY_API_KEY}"}
... )

Model Configuration

ModelConfig

Union type supporting both a simple string (e.g., "openai:gpt-4.1") and a DetailedModelConfig object. Either form is resolved through promptise.models.resolve_model, so provider aliases (azure:, foundry:, gemini:, bedrock:, ...) work in both, and credentials given in the file (api_key, endpoint, api_version, region, project) satisfy the provider's environment-variable check. See SuperAgent Files for an Azure example.

DetailedModelConfig

promptise.superagent_schema.DetailedModelConfig

Bases: BaseModel

Detailed model configuration with provider-specific parameters.

This configuration format allows fine-grained control over model initialization, including API keys, temperature, token limits, and provider-specific parameters.

Attributes:

Name	Type	Description
provider	str	Model provider (e.g., "openai", "anthropic", "ollama").
name	str	Model name/ID (e.g., "gpt-4.1", "claude-opus-4.5").
api_key	str | None	Optional API key (supports ${ENV_VAR} syntax).
temperature	float | None	Optional temperature parameter (0.0-2.0).
max_tokens	int | None	Optional maximum tokens for generation.
timeout	int | None	Optional request timeout in seconds.
base_url	str | None	Optional custom API base URL.
extra	dict[str, Any]	Additional provider-specific parameters.

Examples:

>>> config = DetailedModelConfig(
...     provider="openai",
...     name="gpt-4.1",
...     api_key="${OPENAI_API_KEY}",
...     temperature=0.7
... )

Azure OpenAI — the model, the deployment you named it, and where it lives are separate fields::

model:
  provider: azure
  model: gpt-4o
  deployment: chat-prod
  endpoint: https://my-resource.openai.azure.com/
  api_key: ${AZURE_OPENAI_API_KEY}
  api_version: "2024-10-21"

The common words (deployment, api_key, endpoint, api_version, region, project) are translated to each provider's own keyword arguments exactly like :class:promptise.models.Model; a value set here counts as provided, so the matching environment variable is not required. name: and model: are synonyms.

warn_direct_key(v) classmethod

Warn if API key appears to be a direct value (not env var).

MemorySection

promptise.superagent_schema.MemorySection

Bases: BaseModel

Memory configuration section for .superagent files.

Attributes:

Name	Type	Description
provider	Literal['in_memory', 'chroma', 'mem0']	Memory provider type ("in_memory", "chroma", "mem0").
collection	str	ChromaDB collection name (chroma provider).
persist_directory	str | None	ChromaDB persistence path (chroma provider).
user_id	str	Mem0 user scope (mem0 provider).
agent_id	str | None	Mem0 agent scope (mem0 provider).

Examples:

>>> config = MemorySection(provider="chroma", persist_directory=".promptise/chroma")
>>> config = MemorySection(provider="mem0", user_id="user-123")

SandboxConfigSection

promptise.superagent_schema.SandboxConfigSection

Bases: BaseModel

Sandbox configuration section for .superagent files.

Attributes:

Name	Type	Description
backend	Literal['docker', 'gvisor']	Container backend (docker, gvisor).
image	str	Base container image.
cpu_limit	int	Maximum CPU cores.
memory_limit	str	Maximum memory (e.g., "4G").
disk_limit	str	Size of the writable workspace (e.g., "1G").
pids_limit	int	Maximum number of processes and threads.
network	Literal['none', 'restricted', 'full']	Network isolation mode (none, restricted, full).
persistent	bool	Keep the container after the session ends.
timeout	int	Max execution time in seconds.
workdir	str	Working directory inside container.
env	dict[str, str]	Additional environment variables.
allow_sudo	bool	Allow sudo access in container.

Examples:

>>> config = SandboxConfigSection(
...     backend="gvisor",
...     cpu_limit=2,
...     memory_limit="4G"
... )

CrossAgentConfig

promptise.superagent_schema.CrossAgentConfig

Bases: BaseModel

Cross-agent reference configuration.

Defines a reference to another agent's .superagent configuration file, allowing multi-agent coordination and delegation.

Attributes:

Name	Type	Description
file	str	Path to referenced .superagent file (relative to current file).
description	str	Human-readable description for tool discovery.
timeout	float | None	Seconds to wait for this agent's answer (overrides the file's delegation_timeout).

Examples:

>>> config = CrossAgentConfig(
...     file="./agents/math_specialist.superagent",
...     description="Specialized math and calculation agent"
... )