Otto configuration

Configure Otto agents to customize their behavior, model settings, tool access, and MCP server connections within your Ascend Project.

Organization

The otto.yaml configuration must be located within a dedicated otto directory in your Ascend Project:

Screenshot

File tree

├── otto
│   ├── agents
│   │   └── custom_agent.md
│   ├── mcp.yaml
│   ├── otto.yaml
│   └── rules
│       └── demo_welcome.yaml
│       └── git_commits.yaml

Configuration structure

otto/otto.yaml

otto:
  default_model: <model-identifier>  # Default model for all agents
  model_settings:                     # Default model settings
    temperature: <0.0-1.0>
    max_tokens: <number>
  agents:
    <agent_id>:
      additional_instructions: ...    # Append to system instructions
      instructions: ...               # Replace system instructions entirely
      max_turns: ...                  # Override conversation turn limit
      model: ...                      # Override model for this agent
      model_settings: ...             # Override model settings
      mcp_servers: ...                # Grant access to MCP servers
      tools: ...                      # Configure tool access

Model configuration

Default model

Set a default model for all agents:

otto/otto.yaml

otto:
  default_model: gpt-4.1

Model settings

Configure model parameters like temperature and token limits:

otto/otto.yaml

otto:
  model_settings:
    temperature: 0.7        # Response randomness (0.0-1.0)
    max_tokens: 4096        # Maximum response length

Per-agent model override

Override the model for specific agents:

otto/otto.yaml

otto:
  agents:
    chat:
      model: gpt-4.1
      model_settings:
        temperature: 0.3    # Lower for more deterministic responses

    "Code Reviewer":
      model: claude-3-5-sonnet
      model_settings:
        temperature: 0.2

Extended thinking (Claude models)

Enable extended thinking for Claude models to improve reasoning on complex tasks. Extended thinking allows Claude to work through problems step-by-step before responding.

otto/otto.yaml

otto:
  agents:
    chat:
      model: bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0
      model_settings:
        thinking:
          type: enabled
          budget_tokens: 4096  # Max tokens for reasoning (1024-16384)

Setting	Description
type	Set to enabled to activate extended thinking
budget_tokens	Maximum tokens Claude can use for reasoning. Higher values allow deeper analysis but increase latency and cost.

Extended thinking is most useful for:

• Complex code analysis and debugging
• Multi-step planning tasks
• Problems requiring careful reasoning

Agent configuration

Override system instructions

Use additional_instructions to append to the default system instructions, or use instructions to completely replace them:

otto/otto.yaml

otto:
  agents:
    chat:
      additional_instructions: |
        Always provide code examples when explaining concepts.
        Use markdown formatting for code blocks.

    commit_message:
      additional_instructions: Use conventional commits format with an emoji prefix.

Conversation limits

Override the maximum number of turns for any agent:

otto/otto.yaml

otto:
  agents:
    chat:
      max_turns: 100

    "Pipeline Monitor":
      max_turns: 50

MCP server access

Grant agents access to specific MCP servers configured in mcp.yaml (see MCP guide):

otto/otto.yaml

otto:
  agents:
    chat:
      mcp_servers:
        - slack
        - github

    "Pipeline Monitor":
      mcp_servers:
        - slack
        - pagerduty

Access patterns:

• Specific agents: Only listed agents can access the MCP servers
• Granular control: Different agents can have different server access levels
• Multiple servers: Agents can access multiple MCP servers simultaneously

Tool configuration

Control which tools an agent can use:

otto/otto.yaml

otto:
  agents:
    "Read Only Agent":
      tools:
        - read_file
        - search_files
        - list_directory

    "Full Access Agent":
      tools:
        - "*"  # All tools

Built-in agents

You can customize both custom agents and built-in agents:

Agent ID	Description
chat	Otto Chat: general-purpose conversation
commit_message	Generates git commit messages

otto/otto.yaml

otto:
  agents:
    chat:
      max_turns: 100
      mcp_servers:
        - slack
      model_settings:
        temperature: 0.7

    commit_message:
      additional_instructions: |
        Use conventional commits format.
        Include a scope when applicable.
        Keep the first line under 72 characters.

Configuration precedence

Settings are applied in order of precedence (highest to lowest):

1. otto.yaml overrides: Highest priority
2. Agent definition in otto/agents/*.md
3. Model selected in Chat UI (for interactive sessions)
4. Default settings (default_model, model_settings)
5. Provider defaults

Example: If you set temperature: 0.3 in otto.yaml for the chat agent, it will override any temperature setting in the agent's markdown definition.

Complete example

otto/otto.yaml

otto:
  # Defaults for all agents
  default_model: gpt-4.1
  model_settings:
    temperature: 0.7
    max_tokens: 4096

  agents:
    # Customize built-in chat agent
    chat:
      max_turns: 100
      model_settings:
        temperature: 0.5
      mcp_servers:
        - slack
        - github
      additional_instructions: |
        When discussing code changes, always explain the reasoning.
        Prefer simple solutions over complex ones.

    # Customize built-in commit message agent
    commit_message:
      model_settings:
        temperature: 0.2  # More deterministic
      additional_instructions: |
        Use conventional commits format: type(scope): message
        Use these types: feat, fix, docs, refactor, test, chore

    # Configure custom agent
    "Code Reviewer":
      model: claude-3-5-sonnet
      model_settings:
        temperature: 0.3
        reasoning: true
      mcp_servers:
        - github

    # Configure another custom agent
    "Pipeline Monitor":
      max_turns: 50
      mcp_servers:
        - slack
        - pagerduty

Next steps

• Set up MCP servers following the MCP Setup Guide
• Create custom agents with specialized capabilities
• Configure Otto Automations for event-driven workflows
• Define custom rules for project-specific guidance