Use prompts in agents

Add a published prompt to an agent so that it is used as the agent’s instruction at runtime.

Before you begin

Make sure that you have:

• A running agentregistry instance
• A published prompt in the registry (see Create and publish prompts)
• An agent project created with arctl agent init

Add a prompt to an agent

1. Navigate to your agent project directory.

   cd my-agent

2. Add a prompt reference to the agent manifest. The --registry-prompt-name flag specifies the prompt name as published in the registry.

   arctl agent add-prompt reviewer --registry-prompt-name code-review

   Example output:

   ✓ Added prompt 'reviewer' to agent.yaml

   This adds a prompts section to your agent.yaml:

   prompts:
     - name: reviewer
       registryURL: http://localhost:12121
       registryPromptName: code-review
   You can pin a specific version by using the --registry-prompt-version flag. If omitted, the latest version is resolved at runtime.

3. To use a prompt from a different registry, use the --registry-url flag.

   arctl agent add-prompt reviewer --registry-prompt-name code-review --registry-url https://registry.example.com

How prompts are resolved at runtime

When you run the agent with arctl agent run, the following happens automatically:

1. The CLI reads the prompts section from agent.yaml.
2. For each prompt reference, the CLI fetches the prompt content from the registry’s REST API.
3. The resolved prompt content is written to a prompts.json file in the agent’s config directory.
4. The agent’s prompts_loader.py (autogenerated) reads prompts.json at startup.
5. The build_instruction() function returns the resolved prompt content as the agent’s instruction, replacing the default instruction.

arctl agent run .