Search Docs…

Search Docs…

Reference

Agent Configuration

This document provides comprehensive reference for all configuration objects in CoAgent, including agents, model providers, sandbox configurations, tool providers, and OAuth integrations.

Agent Configuration

Agent configurations define the behavior, personality, and capabilities of AI agents.

Schema

{
  "id": "agent-uuid",
  "name": "agent-name",
  "description": "Agent description",
  "preamble": "System prompt that defines agent behavior",
  "update_time": "2024-01-15T10:30:00Z",
  "project_id": "project-uuid"
}

Parameters

Parameter

Type

Required

Description

id

string

Auto-generated

Unique identifier (UUID) for the agent

name

string

Yes

Unique name for the agent (no spaces or special characters)

description

string

No

Human-readable description of the agent's purpose

preamble

string

Yes

System prompt that defines agent behavior and personality

update_time

string

Auto-generated

ISO 8601 timestamp of last update

project_id

string

No

Project identifier for organization (future use)

Examples

Customer Support Agent

{
  "name": "customer-support-specialist",
  "description": "Specialized agent for handling customer inquiries with empathy and efficiency",
  "preamble": "You are a professional customer support specialist with extensive experience in resolving customer issues. Your approach should be:\n\n1. **Empathetic**: Always acknowledge the customer's feelings and frustrations\n2. **Solution-oriented**: Focus on providing clear, actionable solutions\n3. **Professional**: Maintain a friendly but professional tone\n4. **Proactive**: Anticipate follow-up questions and provide comprehensive answers\n5. **Escalation-aware**: Know when to escalate complex issues to human agents\n\nAvailable tools: customer_lookup, order_status, refund_processor, knowledge_base_search\n\nAlways start by understanding the customer's specific situation before providing solutions."
}

Technical Documentation Agent

{
  "name": "technical-documentation-writer",
  "description": "Agent specialized in creating clear, comprehensive technical documentation",
  "preamble": "You are a technical documentation specialist who excels at explaining complex concepts clearly. Your documentation should be:\n\n1. **Clear and concise**: Use simple language while maintaining technical accuracy\n2. **Well-structured**: Organize information logically with proper headings and sections\n3. **Example-rich**: Include practical examples and code snippets where relevant\n4. **Audience-aware**: Adapt complexity based on the intended audience level\n5. **Comprehensive**: Cover edge cases and common pitfalls\n\nFormat your responses in Markdown with appropriate code blocks, tables, and lists. Include prerequisites, step-by-step instructions, and troubleshooting sections where applicable."
}

Sales Assistant Agent

{
  "name": "sales-assistant",
  "description": "Intelligent sales assistant for product recommendations and lead qualification",
  "preamble": "You are a knowledgeable sales assistant focused on helping customers find the right products and solutions. Your approach should be:\n\n1. **Consultative**: Ask questions to understand customer needs before recommending\n2. **Product-focused**: Have deep knowledge of product features and benefits\n3. **Value-driven**: Emphasize how solutions address specific customer pain points\n4. **Trust-building**: Be honest about limitations and alternatives\n5. **Goal-oriented**: Guide conversations toward qualified leads or sales\n\nAvailable tools: product_catalog, pricing_calculator, inventory_check, competitor_comparison\n\nAlways qualify the customer's budget, timeline, and decision-making process while providing helpful information."
}

Best Practices

Preamble Guidelines

  • Be specific: Define exact behaviors and expectations

  • Include context: Mention available tools and capabilities

  • Set boundaries: Clarify what the agent should and shouldn't do

  • Define personality: Establish tone, style, and approach

  • Provide examples: Include sample behaviors or responses

Naming Conventions

  • Use lowercase with hyphens: customer-support-agent

  • Be descriptive but concise: technical-docs-writer

  • Avoid spaces and special characters

  • Consider environment prefixes: prod-customer-support

Model Provider Configuration

Model providers connect CoAgent to various AI services like OpenAI, Anthropic, or local models.

Schema

{
  "id": "provider-uuid",
  "name": "Provider Display Name",
  "provider_type": "openai|anthropic|local|custom",
  "api_key": "provider-api-key",
  "base_url": "https://api.provider.com",
  "available_models": ["model-1", "model-2"],
  "default_model": "default-model-name",
  "rate_limits": {
    "requests_per_minute": 100,
    "tokens_per_minute": 10000
  },
  "update_time": "2024-01-15T10:30:00Z"
}

Parameters

Parameter

Type

Required

Description

id

string

Auto-generated

Unique identifier for the provider

name

string

Yes

Display name for the provider

provider_type

string

Yes

Type of provider (openai, anthropic, local, custom)

api_key

string

Yes

API key or authentication token

base_url

string

No

Custom base URL (for local/custom providers)

available_models

array

Yes

List of available model names

default_model

string

No

Default model to use if not specified

rate_limits

object

No

Rate limiting configuration

update_time

string

Auto-generated

ISO 8601 timestamp of last update

Provider Types

OpenAI Provider

{
  "name": "OpenAI Production",
  "provider_type": "openai",
  "api_key": "sk-...",
  "available_models": [
    "gpt-4",
    "gpt-4-turbo",
    "gpt-3.5-turbo",
    "gpt-3.5-turbo-16k"
  ],
  "default_model": "gpt-4",
  "rate_limits": {
    "requests_per_minute": 60,
    "tokens_per_minute": 90000
  }
}

Anthropic Provider

{
  "name": "Anthropic Claude",
  "provider_type": "anthropic",
  "api_key": "sk-ant-...",
  "available_models": [
    "claude-3-opus-20240229",
    "claude-3-sonnet-20240229",
    "claude-3-haiku-20240307"
  ],
  "default_model": "claude-3-sonnet-20240229",
  "rate_limits": {
    "requests_per_minute": 50,
    "tokens_per_minute": 40000
  }
}

Local/Self-Hosted Provider

{
  "name": "Local Ollama",
  "provider_type": "local",
  "base_url": "http://localhost:11434",
  "available_models": [
    "llama2",
    "codellama",
    "mistral",
    "neural-chat"
  ],
  "default_model": "llama2",
  "rate_limits": {
    "requests_per_minute": 1000,
    "tokens_per_minute": 100000
  }
}

Custom Provider

{
  "name": "Custom API Provider",
  "provider_type": "custom",
  "api_key": "custom-token",
  "base_url": "https://my-custom-api.com/v1",
  "available_models": ["custom-model-1", "custom-model-2"],
  "default_model": "custom-model-1"
}

Sandbox Configuration

Sandbox configurations define the runtime environment for agent execution, including model parameters, tools, and system prompts.

Schema

{
  "id": "sandbox-uuid",
  "name": "Configuration Name",
  "project_id": "project-uuid",
  "system_prompt": "System-level prompt",
  "tools": [
    {
      "id": "tool-provider-id",
      "tool_names": ["tool1", "tool2"]
    }
  ],
  "selected_model_reference": {
    "provider_id": "provider-uuid",
    "provider_name": "Provider Name",
    "model_name": "model-name"
  },
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 2048,
    "top_p": 1.0
  },
  "type": "System|User",
  "category": "category-name",
  "description": "Optional description",
  "custom": {
    "additional": "custom fields"
  },
  "update_time": "2024-01-15T10:30:00Z"
}

Parameters

Parameter

Type

Required

Description

id

string

Auto-generated

Unique identifier for the configuration

name

string

Yes

Display name for the configuration

project_id

string

No

Project identifier for organization

system_prompt

string

Yes

System-level prompt for the sandbox

tools

array

No

Available tools in this sandbox

selected_model_reference

object

No

Default model for this sandbox

parameters

object

Yes

Model generation parameters

type

string

Yes

Configuration type (System or User)

category

string

Yes

Category for organization

description

string

No

Optional description

custom

object

No

Custom metadata fields

update_time

string

Auto-generated

ISO 8601 timestamp

Tool Reference Schema

Parameter

Type

Required

Description

id

string

Yes

Tool provider identifier

tool_names

array

Yes

List of tool names or ["*"] for all tools

Model Reference Schema

Parameter

Type

Required

Description

provider_id

string

Yes

Model provider identifier

provider_name

string

Yes

Display name of the provider

model_name

string

Yes

Name of the specific model

Parameters Schema

Parameter

Type

Default

Description

temperature

float

0.7

Randomness in model output (0.0-2.0)

max_tokens

integer

2048

Maximum tokens to generate

top_p

float

1.0

Nucleus sampling parameter (0.0-1.0)

Examples

Customer Support Configuration

{
  "name": "Customer Support Production",
  "project_id": "customer-service-project",
  "system_prompt": "You are operating in a customer support environment. Prioritize customer satisfaction while following company policies. Be empathetic, solution-oriented, and professional.",
  "tools": [
    {
      "id": "customer-tools",
      "tool_names": ["customer_lookup", "order_search", "refund_processor"]
    },
    {
      "id": "knowledge-base",
      "tool_names": ["*"]
    }
  ],
  "selected_model_reference": {
    "provider_id": "openai-prod",
    "provider_name": "OpenAI Production",
    "model_name": "gpt-4"
  },
  "parameters": {
    "temperature": 0.3,
    "max_tokens": 1024,
    "top_p": 0.9
  },
  "type": "System",
  "category": "customer-support",
  "description": "Production configuration for customer support agents with controlled creativity and comprehensive tool access"
}

Creative Writing Configuration

{
  "name": "Creative Writing Assistant",
  "system_prompt": "You are a creative writing assistant. Help users develop compelling narratives, characters, and prose. Be imaginative, supportive, and provide constructive feedback.",
  "tools": [
    {
      "id": "writing-tools",
      "tool_names": ["grammar_check", "style_analyzer", "thesaurus_lookup"]
    }
  ],
  "selected_model_reference": {
    "provider_id": "anthropic-prod",
    "provider_name": "Anthropic Claude",
    "model_name": "claude-3-opus-20240229"
  },
  "parameters": {
    "temperature": 0.8,
    "max_tokens": 3000,
    "top_p": 0.95
  },
  "type": "User",
  "category": "creative",
  "description": "High creativity configuration for creative writing tasks"
}

Technical Analysis Configuration

{
  "name": "Technical Analysis Engine",
  "system_prompt": "You are a technical analysis system. Provide accurate, detailed technical assessments based on data and established methodologies. Be precise, objective, and thorough.",
  "tools": [
    {
      "id": "analysis-tools",
      "tool_names": ["data_processor", "chart_generator", "statistical_analyzer"]
    },
    {
      "id": "external-data",
      "tool_names": ["market_data_api", "financial_reports"]
    }
  ],
  "selected_model_reference": {
    "provider_id": "openai-prod",
    "provider_name": "OpenAI Production", 
    "model_name": "gpt-4"
  },
  "parameters": {
    "temperature": 0.1,
    "max_tokens": 2048,
    "top_p": 0.8
  },
  "type": "System",
  "category": "analysis",
  "description": "Low temperature configuration for precise technical analysis"
}

Tool Provider Configuration

Tool providers define external services and APIs that agents can interact with.

Schema

{
  "id": "tool-provider-uuid",
  "name": "Provider Name",
  "provider_type": "mcp|http|local|custom",
  "configuration": {
    // Provider-specific configuration
  },
  "available_tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "parameters": {
        // Tool parameter schema
      }
    }
  ],
  "authentication": {
    "type": "bearer|basic|api_key|oauth",
    "credentials": {
      // Authentication details
    }
  },
  "update_time": "2024-01-15T10:30:00Z"
}

MCP (Model Context Protocol) Provider

{
  "name": "GitHub Integration",
  "provider_type": "mcp",
  "configuration": {
    "transport_type": "http",
    "endpoint": "https://api.githubcopilot.com/mcp",
    "timeout_seconds": 30
  },
  "authentication": {
    "type": "bearer",
    "credentials": {
      "token": "github-token"
    }
  },
  "available_tools": [
    {
      "name": "search_repositories",
      "description": "Search for GitHub repositories",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {"type": "string"},
          "sort": {"type": "string", "enum": ["stars", "forks", "updated"]},
          "order": {"type": "string", "enum": ["asc", "desc"]}
        },
        "required": ["query"]
      }
    }
  ]
}

HTTP API Provider

{
  "name": "Weather Service",
  "provider_type": "http",
  "configuration": {
    "base_url": "https://api.weather.com/v1",
    "default_headers": {
      "Accept": "application/json",
      "User-Agent": "CoAgent/1.0"
    },
    "timeout_seconds": 15
  },
  "authentication": {
    "type": "api_key",
    "credentials": {
      "header_name": "X-API-Key",
      "api_key": "weather-api-key"
    }
  },
  "available_tools": [
    {
      "name": "get_current_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"},
          "units": {"type": "string", "enum": ["metric", "imperial"]}
        },
        "required": ["location"]
      }
    }
  ]
}

Local Process Provider

{
  "name": "IT Tickets System",
  "provider_type": "local",
  "configuration": {
    "executable_path": "./target/debug/it-tickets-server",
    "working_directory": "/opt/coagent/tools",
    "environment_variables": {
      "DATABASE_URL": "sqlite://tickets.db",
      "LOG_LEVEL": "info"
    }
  },
  "available_tools": [
    {
      "name": "create_ticket",
      "description": "Create a new IT support ticket",
      "parameters": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "description": {"type": "string"},
          "priority": {"type": "string", "enum": ["low", "medium", "high", "urgent"]},
          "category": {"type": "string"}
        },
        "required": ["title", "description"]
      }
    }
  ]
}

OAuth Configuration

OAuth configurations enable secure authentication with external services.

Schema

{
  "id": "oauth-config-uuid",
  "name": "Service Name",
  "client_id": "oauth-client-id",
  "client_secret": "oauth-client-secret",
  "authorization_url": "https://provider.com/oauth/authorize",
  "token_url": "https://provider.com/oauth/token",
  "scopes": ["scope1", "scope2"],
  "redirect_uri": "https://coagent.example.com/oauth/callback",
  "provider_type": "github|google|custom",
  "update_time": "2024-01-15T10:30:00Z"
}

Parameters

Parameter

Type

Required

Description

id

string

Auto-generated

Unique identifier

name

string

Yes

Display name for the OAuth provider

client_id

string

Yes

OAuth client ID

client_secret

string

Yes

OAuth client secret

authorization_url

string

Yes

OAuth authorization endpoint

token_url

string

Yes

OAuth token endpoint

scopes

array

No

Required OAuth scopes

redirect_uri

string

Yes

Authorized redirect URI

provider_type

string

Yes

Type of OAuth provider

Examples

GitHub OAuth

{
  "name": "GitHub Integration",
  "client_id": "github-client-id",
  "client_secret": "github-client-secret",
  "authorization_url": "https://github.com/login/oauth/authorize",
  "token_url": "https://github.com/login/oauth/access_token",
  "scopes": ["repo", "user:email"],
  "redirect_uri": "https://coagent.example.com/oauth/github/callback",
  "provider_type": "github"
}

Google Workspace OAuth

{
  "name": "Google Workspace",
  "client_id": "google-client-id",
  "client_secret": "google-client-secret", 
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_url": "https://oauth2.googleapis.com/token",
  "scopes": ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/calendar"],
  "redirect_uri": "https://coagent.example.com/oauth/google/callback",
  "provider_type": "google"
}

Environment Variables

CoAgent supports configuration via environment variables for sensitive data and deployment-specific settings.

Core Configuration

Variable

Description

Default

COAGENT_HOST

Server bind address

0.0.0.0

COAGENT_PORT

Server port

3000

RUST_LOG

Logging level

info

DATABASE_URL

Database connection string

sqlite://coagent.db

DATA_DIR

Data storage directory

./data

Model Provider Configuration

Variable

Description

OPENAI_API_KEY

OpenAI API key

ANTHROPIC_API_KEY

Anthropic API key

COHERE_API_KEY

Cohere API key

HUGGINGFACE_API_KEY

Hugging Face API key

External Service Configuration

Variable

Description

GITHUB_TOKEN

GitHub API token

SLACK_BOT_TOKEN

Slack bot token

DISCORD_BOT_TOKEN

Discord bot token

WEBHOOK_SECRET

Webhook verification secret

Security Configuration

Variable

Description

JWT_SECRET

JWT signing secret

CORS_ORIGINS

Allowed CORS origins (comma-separated)

RATE_LIMIT_REQUESTS

Rate limit: requests per minute

RATE_LIMIT_BURST

Rate limit: burst capacity

Example Environment File

# .env file for CoAgent configuration

# Server Configuration
COAGENT_HOST=0.0.0.0
COAGENT_PORT=3000
RUST_LOG=info
DATABASE_URL=postgresql://user:pass@localhost/coagent
DATA_DIR=/opt/coagent/data

# Model Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# External Services
GITHUB_TOKEN=ghp_...
SLACK_BOT_TOKEN=xoxb-...

# Security
JWT_SECRET=your-jwt-secret-here
CORS_ORIGINS=https://app.example.com,https://admin.example.com
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_BURST=20

# Feature Flags
ENABLE_OAUTH=true
ENABLE_WEBHOOKS=true
ENABLE_METRICS=true

Configuration Validation

CoAgent validates all configurations to ensure proper functionality and security.

Common Validation Rules

Agent Configuration

  • name: Must be unique, alphanumeric with hyphens only

  • preamble: Must not be empty

  • Maximum preamble length: 10,000 characters

Model Provider

  • api_key: Must not be empty for cloud providers

  • available_models: Must contain at least one model

  • Rate limits must be positive integers

Sandbox Configuration

  • temperature: Must be between 0.0 and 2.0

  • max_tokens: Must be between 1 and 32,768

  • top_p: Must be between 0.0 and 1.0

Tool Provider

  • Tool names must be unique within provider

  • Parameter schemas must be valid JSON Schema

  • Authentication credentials must match type

Configuration Testing

Test your configurations before deployment:

# Validate configuration files
coagent validate --config agent-config.json
coagent validate --config provider-config.json

# Test provider connections
coagent test-provider --name "OpenAI Production"

# Validate tool provider
coagent test-tools --provider "GitHub Integration"

# Run configuration health check
coagent health-check --full

Migration and Versioning

Configuration Migration

When upgrading CoAgent versions, configurations may need migration:

# Backup existing configurations
coagent backup --output backup-$(date +%Y%m%d).tar.gz

# Migrate configurations to new version
coagent migrate --from v1.0 --to v1.1

# Validate migrated configurations
coagent validate --all

Version Compatibility

CoAgent Version

Config Version

Breaking Changes

v1.0.x

v1

Initial release

v1.1.x

v1.1

Added OAuth support

v1.2.x

v1.2

Enhanced tool providers

v2.0.x

v2

Major schema changes

This comprehensive configuration reference ensures proper setup and management of all CoAgent components for optimal performance and functionality.