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

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_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, 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 ¶

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

`to_model_string()` ¶

`to_server_specs()` ¶

`validate_env_vars()` ¶

`promptise.superagent.SuperAgentConfig` ¶

`init(*, model, model_kwargs=None, servers, instructions=None, trace=True, 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.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` ¶