AI Agent

An AI Agent in the Crafting system is a user-defined specification for conducting agentic conversations or autonomous loops. The specification defines the details of the environment that an AI agent can interact with, including:

Execution environment, backed by sandboxes.
Tools, including the built-in Crafting tools and external tools via MCP.
Inter-agent collaboration (an agent team).

Essential Information

The following information is required from an AI Agent:

Brief — a very short summary of what the agent will do.
Details — short, but with enough information to let the system know how to use the agent; for example, what should be included in the prompt.
Instructions — this becomes part of the system prompt when the agent starts to run.

Note: both Brief and Details are provided for the system that uses the agent, not for the agent itself. The Instructions, as part of the system prompt, are used by the agent itself.

Agentic Environment

The rest of the specification describes the actual environment the agent runs inside, including:

Execution environment — if needed, a dedicated sandbox is created for the agent.
Tools — the selection of MCP tools and the related tool call policies.
Collaboration — the list of sub agents that can be spawned and work in parallel to get complex jobs done.
Model — the LLM model configuration.

Execution Environment

An Execution Environment is not needed if the Instructions provide enough context and the tool selection gives sufficient interaction.

For more complicated situations, involving:

large scale context, such as source code or complex documents;
state persistence, where the artifacts generated or updated during execution need to be preserved and reused in future follow-ups;
full featured operating system access, including access to external services that require specific configurations from an operating system;

an Execution Environment can be defined to create a dedicated sandbox from a template.

Note: when an Execution Environment is defined, the dedicated sandbox is created for the conversation before it starts. The lifetime of that sandbox is linked to the conversation — it is deleted when the conversation is archived or deleted.

Flexible Environment

When a template is used in a defined Execution Environment, the agent works in an owned, dedicated sandbox. This may, however, prevent the agent from collaborating with other agents and from sharing the environment those agents are working in.

For this case, do not define an Execution Environment. Instead, enable transfer_to_workspace in the tool selection and add context similar to the following to the Instructions:

Only use a sandbox if the user explicitly names one.
Otherwise, create a new sandbox from the <TEMPLATE> template.
Never list or look up existing sandboxes to pick one.
If a workspace is explicitly named, use it. Otherwise use <WORKSPACE>.
Transfer to the workspace to perform the tasks inside.

Replace <TEMPLATE> and <WORKSPACE> accordingly.

With that, the agent can be started with a prompt like:

Use sandbox <SANDBOX-NAME> to complete the task: ...

Or simply with a task prompt that does not name a sandbox at all.

Note: when an existing sandbox is specified, it is not linked to the conversation and keeps its original lifetime. See Transfer to Workspace for a walkthrough.

Tools

Tools are an important part of an agentic environment, and define the capability of an agent. The specification can select both built-in tools and external MCP tools.

The built-in system tools are a collection of tools that let the agent interact with the Crafting system, such as sandbox management.

External MCP tools can be added to the environment so that the agent is able to perform business-specific tasks.

Collaboration

When a job is complex and requires any of the following:

context to be limited and focused, so the agent can perform better;
parts of the job take time and can run in parallel;

an agent team can be used to perform more efficiently.

An AI Agent may include a number of sub agents, which automatically activates the capability of executing as a team. During the conversation, additional tools are injected to list sub agents and to spawn child conversations with sub agents in parallel. The output of the child conversations is propagated back to the parent agent conversation, and it is up to the parent agent to decide how to process that output. The parent agent may generate follow-up prompts to resume child conversations and expect further output.

When adding sub agents to an AI Agent, wildcards such as * and ? can be used in the sub agent name. This gives a parent agent the flexibility to coordinate with the existing agents in general, instead of being limited to a fixed set of sub agents. See The Team Lead for how this is used to build a general purpose leading agent.

Model

A particular model can be selected for the agent, as well as remapping the models that are implicitly used in the conversation. See LLM Config for how models and their purposes are configured at the org level.

An AI Agent can be defined by a user for personal use. Such an agent is only accessible by its owner.

As an org admin, a set of AI Agents can be defined and shared at the org level. These agents have no owner and can be accessed by all members in the org.

For more details about defining and sharing agents, refer to the Agent Build Guide.