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

1. Follow the Get started guide to set up agentregistry and start the agentregistry daemon.
2. Create an agent, such as with the arctl agent init command.
3. Publish a prompt in agentregistry.

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 (agent.yaml). The --registry-prompt-name flag specifies the prompt name that you used when you published the skill in agentregistry. The following command adds a prompts section to your agent.yaml file.

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

   Example output:

   ✓ Added prompt 'reviewer' to agent.yaml

   Example prompts section in the agent.yaml file:

   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 the agent.yaml file.
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 the prompts.json file at startup.
5. The build_instruction() function returns the resolved prompt content as the agent’s instruction, replacing the default instruction.

arctl agent run .