Agent configuration

An agent needs a name and core_config.instructions. Everything else on this page is optional, and most of it is how you turn a working agent into one you would let near production.

The agent itself

These sit next to core_config, not inside it.

There is no model field. Every reasoning component runs a model pinned after benchmarking for that component's specific job, with no silent substitution when one is unavailable.

Instructions

core_config.instructions is the agent's standing brief, and it is the one core_config field a create request must supply non-empty.

Write it as the operating context you would give a competent new hire: what this agent is responsible for, what it must never do, whose conventions apply. It is delivered to every reasoning component, not just the planner, so a standard you state here reaches the parts that plan, execute, and check the work.

What the agent pays attention to

core_config.domain_dimensions steers what an agent keeps when it learns. Each entry is a name, a description, and optional example values, and you can define up to 20.

{
  "domain_dimensions": [
    {
      "name": "reliability",
      "description": "Practices that keep services resilient under load and failure.",
      "examples": ["retries", "timeouts"]
    },
    {
      "name": "apply_phase",
      "description": "When in the delivery lifecycle the guidance applies.",
      "examples": ["design", "implementation", "operations"]
    }
  ]
}

Leave it out and the agent learns unguided, which is a reasonable default. Set it when an agent is doing narrow work and you want its lessons filed against the axes your team actually reasons in. On a patch, pass null or [] to clear.

Tools

core_config.mcp_servers attaches tool servers over MCP. Each entry needs a name and exactly one of url (HTTP or SSE transport) or command (stdio transport).

Use auth_type with auth_token_env to reference a secret by name rather than embedding it, which is the hosted-safe form. Set allowed_tools when a server offers more than the agent should be able to reach; an agent cannot call a tool that was never registered.

Guardrails

core_config.guardrails_config holds two independent guardrails, pii and prompt_injection. Each is optional, and presence is the switch: leaving one unset is how you run without it. There is no enabled flag to get wrong.

Both run on the way in, before generation starts, which is the only point at which they can still help. They are separate from the grounding gate, which governs what a run may claim on the way out.

PII

{
  "guardrails_config": {
    "pii": {
      "entities": ["PERSON", "EMAIL_ADDRESS", "CREDIT_CARD"],
      "actions": { "PERSON": "anonymize", "CREDIT_CARD": "block", "SSN": "block" },
      "score_threshold": 0.5
    }
  }
}

Each detected entity type takes one of three actions:

The defaults are deliberately not uniform, and worth knowing before you override them:

Payment and identity numbers are blocked rather than masked, because a masked card number is still a card number that reached the boundary. Organization names are logged rather than masked, because masking them usually destroys the task.

Prompt injection

prompt_injection screens for injection and jailbreak attempts using purpose-built classifiers rather than asking a model to police itself, which is the same reasoning behind the grounding gate not using an LLM judge.

Approval gates

This is the part most worth setting deliberately, because the default is the permissive one.

All four of these live inside core_config, not next to it. Putting them at the top level is rejected outright, so this is a loud failure rather than a silent one:

{
  "name": "Collections Assistant",
  "core_config": {
    "instructions": "Chase overdue invoices and propose next actions.",
    "hitl_enabled": true,
    "hitl_autonomy_level": 2
  }
}

That agent pauses at plans, milestones, destructive and external tools, and escalations. The levels run 1 (every gate fires) to 5 (none), so pick the number by how much you want to be asked:

Requiring more than one approver

A quorum needs two things set, not one. hitl_required_approvals above 1 requires hitl_enabled: true and hitl_policy_preset: "milestone_only"; anything else is rejected with a 422 rather than silently collapsing to a single approver.

{
  "core_config": {
    "instructions": "...",
    "hitl_enabled": true,
    "hitl_policy_preset": "milestone_only",
    "hitl_required_approvals": 2
  }
}

The details are what make the control worth anything:

• Each approval must come from a distinct authenticated principal, meaning a distinct API key or portal login. That is not the same as a distinct human, so pair it with your own identity discipline.
• The principal who dispatched the run is excluded from approving it.
• Any single rejection vetoes, regardless of how many approvals were already collected.
• One caller resuming twice replays rather than counting twice, so a double-click cannot manufacture a quorum.

Passing a boolean where the count belongs is rejected rather than quietly read as 1. Under looser handling a stray true would silently downgrade a two-person control to a single approver, which is exactly the failure the field exists to prevent.

Related pages

• Agents API for creating and patching agents
• Reasoning for how gates behave during a run
• Grounded success for what a run must prove before it reports success
• Learning for what domain dimensions steer
• Access control (FGA and RBAC) for who may create and dispatch agents