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

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)` ¶

Load and resolve cross-agent references.

Loads .superagent files referenced in the cross_agents section, with circular reference detection.

Parameters:

Name	Type	Description	Default
`recursive`	`bool`	If True, recursively load cross-agents of cross-agents.	`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).

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.

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`		Raw cross-agent configs (resolved separately).
`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, 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, Any] \| None`	Cross-agent configuration dict.	`None`
`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()` ¶

Convert to kwargs dict for build_agent().

Returns:

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

Note

cross_agents needs special handling to build actual CrossAgent objects - see CLI integration for example.

Examples:

>>> config = loader.to_agent_config()
>>> kwargs = config.to_build_kwargs()
>>> agent = await build_agent(**kwargs)

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, and optionally resolves cross-agent references 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
`tuple[SuperAgentLoader, dict[str, SuperAgentLoader]]`	Tuple of (main_loader, cross_agent_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
>>> 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 (currently "1.0").
`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}).
`auth`	`str \| None`	Optional auth token (supports ${ENV_VAR}).

Examples:

>>> server = HTTPServerConfig(
...     type="http",
...     url="http://127.0.0.1:8000/mcp",
...     headers={"Authorization": "Bearer ${API_TOKEN}"}
... )

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.

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

`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`	Maximum disk space (e.g., "10G").
`network`	`Literal['none', 'restricted', 'full']`	Network isolation mode (none, restricted, full).
`persistent`	`bool`	Keep workspace between runs.
`timeout`	`int`	Max execution time in seconds.
`tools`	`list[str]`	Pre-installed tools list.
`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.

Examples:

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

SuperAgent API Reference¶

SuperAgentLoader¶

promptise.superagent.SuperAgentLoader ¶

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

from_file(file_path, *, _loading_chain=None) classmethod ¶

resolve_cross_agents(*, recursive=True) ¶

resolve_env_vars() ¶

to_agent_config() ¶

to_identity() ¶

to_model_kwargs() ¶

to_model_string() ¶

to_server_specs() ¶

validate_env_vars() ¶

SuperAgentConfig¶

promptise.superagent.SuperAgentConfig ¶

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

to_build_kwargs() ¶

load_superagent_file¶

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

Schema Definitions¶

SuperAgentSchema¶

promptise.superagent_schema.SuperAgentSchema ¶

validate_has_config() ¶

AgentSection¶

promptise.superagent_schema.AgentSection ¶

IdentityConfig¶

promptise.superagent_schema.IdentityConfig ¶

to_identity() ¶

Server Configuration¶

ServerConfig¶

HTTPServerConfig¶

promptise.superagent_schema.HTTPServerConfig ¶

StdioServerConfig¶

promptise.superagent_schema.StdioServerConfig ¶

Model Configuration¶

ModelConfig¶

DetailedModelConfig¶

promptise.superagent_schema.DetailedModelConfig ¶

warn_direct_key(v) classmethod ¶

MemorySection¶

promptise.superagent_schema.MemorySection ¶

SandboxConfigSection¶

promptise.superagent_schema.SandboxConfigSection ¶

CrossAgentConfig¶

promptise.superagent_schema.CrossAgentConfig ¶

`promptise.superagent.SuperAgentLoader` ¶

`init(file_path, schema, *, _loading_chain=None)` ¶

`from_file(file_path, *, _loading_chain=None)` `classmethod` ¶

`resolve_cross_agents(*, recursive=True)` ¶

`resolve_env_vars()` ¶

`to_agent_config()` ¶

`to_identity()` ¶

`to_model_kwargs()` ¶

`to_model_string()` ¶

`to_server_specs()` ¶

`validate_env_vars()` ¶

`promptise.superagent.SuperAgentConfig` ¶

`init(*, model, model_kwargs=None, servers, instructions=None, trace=True, identity=None, cross_agents=None, sandbox=None, memory=None, observe=None, optimize_tools=None, cache=None, approval=None, events=None, adaptive=None, guardrails=None, max_invocation_time=0)` ¶

`to_build_kwargs()` ¶

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

`promptise.superagent_schema.SuperAgentSchema` ¶

`validate_has_config()` ¶

`promptise.superagent_schema.AgentSection` ¶

`promptise.superagent_schema.IdentityConfig` ¶

`to_identity()` ¶

`promptise.superagent_schema.HTTPServerConfig` ¶

`promptise.superagent_schema.StdioServerConfig` ¶

`promptise.superagent_schema.DetailedModelConfig` ¶

`warn_direct_key(v)` `classmethod` ¶

`promptise.superagent_schema.MemorySection` ¶

`promptise.superagent_schema.SandboxConfigSection` ¶

`promptise.superagent_schema.CrossAgentConfig` ¶