Agents

Configure your AI through agents — each with its own LLM, skills, MCP servers, and tools.

Overview

Agents are the central building block in Astralform. Every project has a Main Agent that handles all requests by default. You can create additional specialized agents and use a supervisor to route messages automatically.

All configuration — LLM provider, skills, MCP servers, and platform tools — is managed through agent detail pages.

Main Agent

Every project starts with a Main Agent. It auto-inherits all project resources (skills, MCP servers, tools), so single-agent setups require no extra configuration.

• The Main Agent cannot be deleted
• New resources added to the project are automatically available to the Main Agent
• When no agent_name is specified in a chat request, the Main Agent handles it

Agent Detail Page

Click any agent from the agents list to open its detail page. Configuration is organized into five tabs:

Model Tab

Configure the LLM provider, model, and generation parameters for this agent.

1. Go to Agents and click an agent
2. On the Model tab, select a provider (OpenAI, Anthropic, Groq, Ollama)
3. Choose a model and enter the provider API key
4. Configure additional model parameters as needed
5. Click Save

Field	Description	Default
Provider / Model	LLM provider and model selection	Inherited from Main Agent
temperature	Controls output randomness (0.0 = deterministic, 2.0 = maximum randomness)	Provider default
thinking_effort	Reasoning depth for thinking-enabled models: low, medium, or high	medium
auto_spawn_enabled	Enables dynamic subagent spawning for complex multi-step tasks	false
sandbox_template	VM template for the agent’s Capsule sandbox: base, browser, code-interpreter-v1, desktop	base
sandbox_envs	Encrypted environment variables injected into the sandbox (key-value pairs)	—

If no LLM is configured on a named agent, it inherits the project’s LLM settings from the Main Agent.

See LLM Providers for provider details and available models.

Auto-Capsule

Agents with non-system skills automatically get a Capsule sandbox — no manual sandbox configuration needed. The sandbox is an isolated Firecracker microVM provisioned using the agent’s sandbox_template. Configure sandbox behavior via the sandbox_template and sandbox_envs fields above.

See Capsule Sandboxes for more details on sandbox templates and lifecycle.

Skills Tab

Assign skills so the agent has access to specialized capabilities.

1. On the Skills tab, see assigned and available skills
2. Click Assign to add a skill, or Unassign to remove one
3. Click Add New Skill to create a skill and assign it in one step

For the Main Agent, all project skills are auto-assigned.

See Skills for the SKILL.md format and best practices.

MCP Tab

Assign MCP servers so the agent can use external tools and databases.

1. On the MCP tab, see assigned and available servers
2. Click Assign or Unassign to manage assignments
3. Click Add New Server to create and assign a server

For the Main Agent, all project MCP servers are auto-assigned.

See MCP Servers for server configuration and examples.

Tools Tab

Assign platform tools (e.g., web search) to the agent.

1. On the Tools tab, see assigned and available tools
2. Toggle tools on or off for this agent

For the Main Agent, all project tools are auto-assigned.

See Platform Tools for available tools.

Connectors Tab

Assign connectors so the agent can access external data sources and services.

1. On the Connectors tab, see assigned and available connectors
2. Click Assign or Unassign to manage connector assignments
3. Each connector provides the agent with access to a specific integration (e.g., Google Drive, Notion, Slack)

Connectors are configured at the project level and then assigned per agent, allowing you to control which agents have access to which integrations.

See Connectors for available connectors and setup instructions.

Creating an Agent

1. Go to Agents
2. Click Add Agent
3. Fill in the details:

Field	Required	Description
Name	Yes	Unique identifier (lowercase, hyphens allowed, e.g., support-agent)
Display Name	No	Human-readable name shown in UI
Description	No	What this agent specializes in (used for supervisor routing)
System Prompt	No	Custom instructions for this agent

4. Click Create, then configure the agent via its detail page

Orchestration

Orchestration controls how multiple agents work together.

Single (Default)

Only the Main Agent handles all requests. Other agents can be addressed directly by name via the SDK.

Supervisor

A supervisor agent automatically routes user messages to the best specialist:

1. Go to Agents
2. In the Orchestration section, select Supervisor
3. Pick a supervisor agent from the dropdown
4. Save

User: "Help me with my billing issue"

Supervisor: [Analyzes request]
            [Routes to support-agent]

support-agent: "I'd be happy to help with your billing..."

The supervisor uses agent descriptions to decide routing, so write clear descriptions for each agent.

Managing Agents

Enable/Disable

Toggle agents on/off without deleting them. Disabled agents are excluded from routing and cannot be addressed by name.

Delete

Click Delete on an agent card and confirm.

The Main Agent cannot be deleted. Deleting an agent removes all its resource assignments.

SDK Integration

SDKs can discover available agents and route messages to specific ones:

// List available agents
let agents = try await astralform.getAgents()

// Send to a specific agent
try await client.streamChat(
    conversationId: "conv_123",
    message: "Review this code",
    agentName: "code-reviewer"
)

See the Agents API for details.

Best Practices

Do	Don’t
Write clear agent descriptions for routing	Leave descriptions empty
Assign only relevant resources to each agent	Give every agent all resources
Use supervisor for 3+ specialized agents	Use supervisor for a single agent
Test routing with different message types	Assume routing works without testing

Next Steps

LLM Providers

Learn about supported LLM providers and models

Skills

Add specialized capabilities to agents