Create and publish an agent

This guide covers the lifecycle of an agent from design to production: defining what it should do, writing the spec, validating it locally, and promoting it to a shared environment.

Before you start

Decide the agent’s purpose and boundaries before opening an editor:

What question or task will it handle?
Which LLM provider and model are appropriate for the job?
What tools or knowledge does it need?
What could go wrong, and which shields or approvals should guard against it?
Which channel or application will invoke it?

Design the spec

An agent spec answers four questions:

Identity — a unique identifier, display name, description, and role tier.
Behavior — system prompt, evaluation strategy, and memory settings.
Capabilities — tools, knowledge bases, and channels.
Protection — shields, empathy rules, and human approval gates.

Keep the spec focused. A single agent that tries to do everything is harder to test, secure, and audit than a small set of specialized agents.

Validate locally

Create an agentspace for local development so your experiments are isolated.
Register any secrets the agent needs, such as API keys, using the registry. Never paste secrets into the agent spec.
Load the spec into the local registry and run a dry-run or sample conversation.
Review the worklog for the test run to confirm the agent used the expected tools and did not make unexpected calls.

Test for safety and quality

Before promoting the agent, test edge cases:

Prompt-injection attempts and off-topic questions.
Missing or malformed tool outputs.
Long conversations that trigger memory summarization.
Approval-required tools to confirm the handoff works.

Use the worklog and traces to verify that shields fired when expected and that the agent stayed within its role tier.

Promote to production

Version the spec in your registry or source-control system.
Package the agentspace as an OCI artifact if you distribute agents across environments.
Deploy to the production runtime using the registry API or CI/CD pipeline.
Enable the channel or application integration that will invoke the agent.
Monitor early traffic for errors, latency, and unexpected behavior.

Best practices

Start with a narrow scope and expand after measuring quality.
Keep system prompts explicit; avoid vague instructions such as “be helpful.”
Reference secrets by name so credentials can be rotated without changing the spec.
Pair powerful tools with shields or approval gates.
Document the intended use and known limitations of each agent.