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
{"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.
{"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.
{"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.