# Agent specification reference

> Agent specification reference - Structure and examples for agent_spec.md—the YAML specification
> Agent Assist creates during design.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-21T05:20:22.327328+00:00` (UTC).

## Primary page

- [Agent specification reference](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [Specification fields](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#specification-fields): In-page section heading.
- [Tool definition](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#tool-definition): In-page section heading.
- [Authentication in specs](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#authentication-in-specs): In-page section heading.
- [Frontend options](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#frontend-options): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#examples): In-page section heading.
- [Simple agent with one tool](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#example-simple-agent): In-page section heading.
- [Multi-tool agent with authentication](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#example-multi-tool-agent): In-page section heading.
- [Multi-page dashboard agent](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/agent-spec-reference.html.md#example-multi-page-agent): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html.md): Linked from this page.
- [Agent Assist](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/index.html.md): Linked from this page.
- [Design an AI agent](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/workflows-and-prompting.html.md#design-an-ai-agent): Linked from this page.
- [list models](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/env-and-commands-reference.html.md#list-models-command): Linked from this page.

## Documentation content

During the [Design an AI agent](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/workflows-and-prompting.html.md#design-an-ai-agent) workflow, Agent Assist writes an `agent_spec.md` file in your working directory. The file is YAML and captures what the agent should do before any implementation code exists. You can review it with stakeholders, edit it by hand, or load it in the [Code an AI agent](https://docs.datarobot.com/en/docs/agentic-ai/agent-assist/workflows-and-prompting.html.md#code-an-ai-agent) workflow.

This page describes each field. All fields are optional while the spec is still evolving; Agent Assist fills them in as you refine the design.

## Specification fields

| Field | Description |
| --- | --- |
| model | DataRobot LLM Gateway model ID (for example anthropic/claude-sonnet-4-5-20250929). Use the list models command in a session, or see Change the Agent Assist LLM, to find available models. |
| system_prompt | Instructions that define the agent's role, tone, and constraints. |
| tools | List of tools the agent can call. Each tool has a function_name, inputs, out, and optionally auth_spec. |
| examples | Sample user queries that illustrate intended behavior. |
| frontend | UI expectations for the Agentic Starter template (see Frontend options). |

### Tool definition

Each entry under `tools` describes one callable function:

| Subfield | Description |
| --- | --- |
| function_name | Name the model uses when requesting the tool. |
| inputs | Arguments the tool accepts. Each input has arg_name, type, and optionally object_schema for structured list or dict values. |
| out | Values the tool returns. Same structure as inputs. |
| auth_spec | Optional. Documents which external service the tool uses and how it authenticates (see Authentication in specs). |

Supported `type` values: `str`, `int`, `float`, `bool`, `list`, `dict`.

### Authentication in specs

When a tool calls an external API, include `auth_spec` so the design records the integration:

```
auth_spec:
  service_name: "External API Service"
  auth_method: api_key
```

| auth_method | Typical use |
| --- | --- |
| api_key | Static key in a header or query parameter (for example OpenAI, Perplexity). |
| oauth2 | User-delegated access with token refresh (for example Salesforce, Google). |
| basic_auth | Username and password. |
| bearer_token | Static bearer token (for example internal services). |
| service_account | Non-human identity with a key file or IAM role (for example GCP, AWS). |
| other | Custom or uncommon authentication. |

The spec documents what authentication is needed. After you implement the agent, configure actual credentials as runtime parameters in the Agentic Starter template infrastructure code. See the template's `AGENTS.md` for the pattern.

### Frontend options

Before simulation or coding, Agent Assist asks whether the default chat UI is enough or you need a custom interface. That choice is stored under `frontend`:

| frontend.type | When to use |
| --- | --- |
| chat | Default single chat window (most agents). |
| multi-page | Distinct pages such as dashboards, tabs, or admin views. |
| custom | Bespoke layout beyond named pages. |

For `multi-page` or `custom`, you can add:

- pages —Short descriptions of each page or view.
- requirements —Optional free-text UI requirements (theme, charts, filters, and so on).

## Examples

### Simple agent with one tool

```
model: anthropic/claude-sonnet-4-5-20250929
system_prompt: You are a helpful weather assistant. When a user asks about weather,
  search for current conditions and present them clearly.
tools:
  - function_name: search_weather
    inputs:
      - arg_name: location
        type: str
    out:
      - arg_name: search_results
        type: str
    auth_spec:
      service_name: Weather API
      auth_method: api_key
examples:
  - What's the weather like in New York?
  - Current conditions in London
frontend:
  type: chat
```

### Multi-tool agent with authentication

```
model: anthropic/claude-sonnet-4-5-20250929
system_prompt: You are a research assistant. Find and summarize information from
  internal documents and the web. Always cite your sources.
tools:
  - function_name: search_internal_docs
    inputs:
      - arg_name: query
        type: str
    out:
      - arg_name: documents
        type: list
        object_schema: "list of {title: str, content: str, url: str}"
    auth_spec:
      service_name: Internal Knowledge Base API
      auth_method: bearer_token
  - function_name: web_search
    inputs:
      - arg_name: query
        type: str
    out:
      - arg_name: results
        type: str
examples:
  - Find recent papers on LLM hallucination
  - What does our internal policy say about data retention?
frontend:
  type: chat
```

### Multi-page dashboard agent

```
model: google/gemini-2.5-pro-preview-05-06
system_prompt: You are a sales analytics assistant. Help users understand pipeline,
  forecast revenue, and identify at-risk deals. Ground answers in tool data.
tools:
  - function_name: get_pipeline_data
    inputs:
      - arg_name: date_range
        type: str
    out:
      - arg_name: deals
        type: list
    auth_spec:
      service_name: Salesforce CRM
      auth_method: oauth2
examples:
  - What's our Q2 pipeline look like?
  - Which deals are at risk of slipping?
frontend:
  type: multi-page
  pages:
    - "Pipeline Overview - deals by stage with filtering"
    - "Revenue Forecast - expected vs actual with confidence bands"
  requirements: "Dark theme charts. Pipeline table sortable by owner and stage."
```