Build AI Agents

An AI Agent in Crafting is a simple specification that can be defined in minutes, without coding or engineering knowledge. It is a powerful and flexible building block for constructing custom, AI powered automation workflows. It keeps agents in a highly focused, well-defined and limited environment; with the right context and tools, agents perform more accurately and efficiently.

Example Walkthrough

Building on the concepts, this section walks through how to create an agent for a specific task. The example used here is scanning for vulnerabilities.

Define the Use of the Agent

The fields Brief and Details help the LLM model understand when to use the agent and how to use it.

Brief should be a very short and accurate statement about what the agent does and when it should be used. This is the only information propagated in a list of agents for the LLM model to pick one during a conversation.

Example: Scan vulnerabilities from a given URL

Details explains how to use the agent, which guides the LLM model to generate the initial user prompt (not the system prompt) and start a conversation, or to generate follow-up prompts to resume the conversation.

Example:

Specify a URL for the agent to scan vulnerabilities.
The agent will report discoveries which can be used as feedback for fixing vulnerabilities.

The Instructions

When the agent starts a conversation, Instructions are used to construct the system prompt. At this stage, the conversation is in a separate, dedicated session, so Brief and Details are unavailable.

Example:

You are responsible for detecting vulnerabilities from web sites.
When asked to scan a given URL,
run `/home/owner/scan/scan.sh -m fast URL` to scan the specified URL for vulnerabilities
and report the findings which is parsed from the output JSON of the command.
Use `--help` to find out more flags and use them according to specific requirements.

Tools

At a minimum, the information provided by Brief, Details and Instructions should be enough to start an agentic conversation. To let the agent interact with other services, tools can be provided.

There are built-in Crafting system tools for interacting with the Crafting system, such as managing sandboxes, and external tools via MCP servers.

If the agent should also be able to start from a GitHub issue:

  1. Add the GitHub MCP server.
  2. Change Brief and Details a bit:
    • Brief: Scan vulnerabilities from a given URL or according to a GitHub issue
    • Details: Specify a URL or a GitHub issue ...
  3. Change the Instructions, replacing When asked to scan a given URL with When a URL is specified, use it as target. Or if a GitHub issue is provided, read the details from the issue and find out the target URL.
  4. Add the GitHub MCP server to the agent.

Execution Environment

An execution environment is not needed if the agent is able to work with instructions and tools alone. In this example, scanning requires pre-installed software, so a sandbox is needed as the execution environment.

Create a template first, and make sure it is well prepared with the scanning software (the instructions above mention the script /home/owner/scan/scan.sh). Then add the Execution Environment using that template.

Test and Iterate

Save the agent with a name — select Personal as Ownership, since it is not ready to be shared — and click the Launch button to test it with a prompt. If anything needs adjustment, edit the agent again.

Publish for Sharing

Once the agent is tested and stable, it can be shared at the org level. Ask an org admin about promoting the agent to be shared across the org.

As an org admin, list the agent from its owner, click the Clone button, and save it with Organization as Ownership.

Ownership and Agent Override

Agents with Ownership set to Organization have no owner, and all members in the organization can start a conversation using that agent.

To build or update an agent, or to customize one according to personal needs, clone an org agent with the SAME NAME as a Personal agent, and it will override the one shared in the org.

For example, consider an agent team shared in the org, with a primary agent named manager and sub agents coding and qa.

A developer who wants to extend the features of the coding agent would:

  1. Clone the coding agent as Personal.
  2. Make changes to the Personal coding agent.
  3. Test and re-iterate by starting a conversation with the manager agent.
  4. Ask an org admin to update the shared coding agent with the modified, Personal version.

In step 3, because the conversation is started by the developer, the Personal agent matching the name is used when looking for the coding agent. This is called agent override.

Another example: a QA engineer wants a temporary change in the qa agent, just for an ad-hoc task. The agent override is applied using steps 1–3 above, by cloning the qa agent as Personal. When it is no longer needed, the Personal qa agent can be deleted, so future conversations go back to the shared qa agent.

Agent Team

For complex tasks, a team of agents can be defined. It often involves:

When defining an agent, Visibility defines how the agent will be used. If it is limited to Sub-agent Only, the agent can only be used as a sub agent, and is not listed as an agent for starting a conversation.

During execution, the LLM model drives the creation of child conversations with sub agents, based on the ongoing conversation with the primary agent. Child conversations run in parallel, each with a separate context so they can stay focused. As the outputs are propagated back to the parent conversation, follow-ups are decided by the LLM model running the parent conversation. A child conversation may further spawn child conversations with its own sub agents. The user is only allowed to interact with the root conversation, originally started with the primary agent.

Transfer to Workspace

When an agent is defined to use a template as its Execution Environment, a dedicated sandbox is always created from that template when a new conversation starts.

For some use cases, an agent needs more flexibility to work on an existing sandbox without using its own dedicated sandbox. In that case, enable Transfer to workspace in the tool selection, without defining an Execution Environment. With that, the agent starts the conversation immediately and leaves it to the LLM model to figure out the target sandbox and workspace, according to the prompt and the Instructions, and to use a special tool call to hand off to the Crafting agent running inside the workspace.

This feature allows an agent to work on an existing Execution Environment, or a set of sub agents to work on the same environment for better information sharing.

See Also