Skip to main content

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:

folder

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)
SettingDescription
typeSet to enabled to activate extended thinking
budget_tokensMaximum 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 IDDescription
chatOtto Chat: general-purpose conversation
commit_messageGenerates 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​

Last updated on