Agentic AI > Agent Assist > Agent specification reference

Agent specification reference¶

During the 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 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."