> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/agent/agents.md).

# Agent Core

{% hint style="success" %}
**For developers:** See [Agents](https://docs.amigo.ai/developer-guide/platform-api/workspaces/agents) for the current Platform API fields, versioning behavior, and examples.
{% endhint %}

An agent version defines the identity and authored guidance that the runtime supplies to the model. It includes an identity object, background text, behavioral guidance, communication patterns, and optional voice configuration. These fields steer model behavior; they are not hard authorization or deterministic policy controls.

## Agent as Interpretive Framework

The agent gives the model a domain-specific frame for interpreting the current conversation and available context. Two agents can respond differently to the same evidence because their identity, background, and guidance emphasize different responsibilities and boundaries.

This interpretive role is critical for compositional systems:

1. **Interpretation.** Background and behavioral guidance help the model decide which available facts matter to the current task.
2. **Workflow behavior.** Agent guidance combines with the active Context Graph state, tools, and channel policy when the runtime generates a response or chooses a modeled action.
3. **Communication.** Identity and communication patterns shape language, tone, and professional boundaries across supported channels.

## Core Components

The Platform API stores an agent as a named parent resource and its immutable versions as configuration snapshots.

* **Identity** - Structured persona fields such as name, role, language, and developer attribution.
* **Background** - Bounded text describing relevant domain context, expertise, and operating stance.
* **Behaviors** - Authored rules and priorities for what the agent should or should not do.
* **Communication patterns** - Authored guidance for tone, wording, and response style.
* **Voice configuration** - An optional voice selection for speech output.

The retired standalone Platform persona resource is not part of this model. Identity is embedded in each agent version, and services resolve the selected agent version through their version-set configuration.

### Persona: Two Layers

Authors commonly divide persona content into two conceptual layers:

* **Identity layer** - Structured attributes such as name, role, and default language.
* **Background layer** - Domain context, expertise, biography, and guiding principles stored in the version's background text.

The API bounds the background field by characters, not tokens. Keep it focused enough for reviewers to understand which guidance belongs globally and which belongs in a specific Context Graph state.

### Behavioral vs. Communication Guidance

The current agent-version schema separates two categories:

* **Behavioral guidance** describes intended scope and priorities, such as refusing to create meal plans or routing medical questions to an approved clinical workflow.
* **Communication patterns** describe expression, such as tone, spelling conventions, sentence structure, and prohibited phrases.

The distinction keeps operating boundaries separate from presentation style. Both are model instructions. Enforce permissions, data access, and external mutations with server-side authorization, tool exposure, validation, and approval policy rather than relying on these fields alone.

## How the Agent Core Connects to Other Systems

The selected agent version contributes to the runtime prompt alongside other components:

* [Functional Memory](/agent/memory.md) and world-model enrichment can supply selected cross-session context.
* The active [Context Graph](/agent/context-graphs.md) supplies state-specific objectives, boundaries, exits, and tool bindings.
* The service and channel determine runtime capabilities, transport behavior, and additional tool exposure.
* Server-side authorization and tool validation determine which operations can actually execute.

Agent versions and Context Graph versions have separate lifecycles. A version set can pin each independently; memory and world-model state are data inputs rather than artifacts versioned with the agent.

## Designing an Agent Core

Treat agent authoring as a specification exercise, not only a branding exercise. Put guidance that should apply broadly in the agent version. Put workflow-specific objectives, boundaries, exits, and tool access in the Context Graph states where reviewers can inspect and test them.

A practical process looks like this:

1. **Interview domain experts.** Capture how they assess severity, personalize guidance, and escalate edge cases.
2. **Translate heuristics into directives.** Express their rules in precise language a model can follow and an auditor can review.
3. **Separate prompt guidance from controls.** Define authored boundaries, then implement enforceable authorization, validation, approval, and escalation paths where required.
4. **Validate with simulations.** Run representative scenarios to confirm the identity behaves as intended before exposing it to users.

## Success Criteria

A well-designed agent version aims for the following traits in representative testing:

* **Appropriate voice and judgment** across the scenarios the team has exercised.
* **Escalation behavior** that matches documented policy in the evaluated cases.
* **Clear boundaries** for what the agent will and will not do, making hand-offs to humans smooth.
* **Reviewable configuration** that separates global agent guidance from state, tool, and channel controls.

If observed behavior diverges from the authored agent fields, inspect the Context Graph, state guidance, available tools, memory inputs, runtime, and channel-specific policy.

{% hint style="info" %}
**Related sections** - See [Context Graphs](/agent/context-graphs.md) for how the agent navigates problem spaces and [Functional Memory](/agent/memory.md) for bounded cross-session context. Classic API users can also review [Dynamic Behaviors](/agent/context-graphs/dynamic-behaviors.md), a Classic-only adaptation mechanism.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/agent/agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.