> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage
> Agents in Compozy are defined and configured using the following structure and patterns.
## Structure
Agents in Compozy follow a consistent structure:
```yaml theme={"dark"}
agents:
- id: string # Unique identifier for the agent
name: string # Optional human-readable name
type: string # Agent type (basic, custom, etc.)
use: string|object # Agent implementation reference
import: string # Path to external agent definition
config: # Agent configuration
provider: string # AI provider identifier
model: string # Model identifier
url: string # API URL
version: string # Optional model version
api_key: string
organization: string
temperature: number
max_tokens: number
top_p: number
frequency_penalty: number
presence_penalty: number
schema: # Optional schema definition
input: object # Input schema for agent parameters
with: object # Agent-specific configuration
env: object # Agent-specific environment variables
tools: array # Available tools
memory: object # Memory configuration
# Custom agent specific
actions: array # List of actions
- id: string # Action identifier
instructions: string # Action instructions
config: object # Custom action configuration
messages: array # List of messages
- role: string # Message role
content: string # Message content
output: object # Action output schema
```
## Basic Usage
Agents can be used in three main ways:
```yaml Package Reference theme={"dark"}
agents:
- id: content_moderator
type: basic
use: compozy/agents:content-moderator@1.0.0
```
```yaml Detailed Package theme={"dark"}
agents:
- id: market_analyst
type: basic
use:
repo: compozy/agents
package: market-analyst
version: 0.2.1
```
```yaml Custom Agent theme={"dark"}
agents:
- id: custom_agent
type: custom
config:
provider: openrouter
model: anthropic/claude-3-sonnet
api_key: "{{ env.OPENROUTER_KEY }}"
url: https://openrouter.ai/api/v1
temperature: 0.3
actions:
- id: analyze
instructions: "Analyze this content"
messages:
- role: user
content: "Please analyze this content: {{ trigger.content }}"
output:
type: object
properties:
analysis: string
confidence: number
```
## Custom Settings
Each agent's configuration can be overridden regardless of whether it's an external package or local import. Use `config` to override provider settings and `with` to override agent-specific parameters:
```yaml External Agent theme={"dark"}
agents:
- id: content_moderator
use: compozy/agents:content-moderator
# Override provider configuration
config:
model: anthropic/claude-3-sonnet
temperature: 0.4
max_tokens: 2000
# Override agent parameters
with:
language: en
threshold: 0.7
```
```yaml Local Import theme={"dark"}
agents:
- id: support_agent
import: ./agents/support.yaml
config: # Override imported configuration
model: gpt-4 # Replace model from import
temperature: 0.7 # Override temperature setting
with:
language: es # Change default language
response_type: detailed # Customize response format
```
## Tools Integration
Agents can be equipped with tools to extend their capabilities and interact with external services. Tools are defined at the agent level:
```yaml Basic Tools theme={"dark"}
agents:
- id: research_assistant
config:
provider: openai
model: gpt-4o-mini
tools:
- id: web_search
use: compozy/tools:web-search@1.0.0
- id: pdf_reader
use: compozy/tools:pdf-reader@1.0.0
```
```yaml Custom Tool Configuration theme={"dark"}
agents:
- id: data_processor
config:
provider: openrouter
model: openai/gpt-4o-mini
tools:
- id: database
use: compozy/tools:database@1.0.0
config:
connection_string: "{{ env.DB_CONNECTION }}"
max_results: 100
- id: api_client
use: compozy/tools:rest-client@1.0.0
with:
base_url: https://api.example.com
headers:
Authorization: "{{ env.API_KEY }}"
```
## Best Practices
* Keep actions focused and single-purpose
* Write clear instructions
* Define comprehensive output schemas
* Start with conservative temperature values
* Adjust max\_tokens based on expected responses
* Use appropriate model versions
* Only include necessary tools
* Configure tool timeouts and limits
* Test tool interactions thoroughly
* Configure memory when needed
* Clear state appropriately
* Consider persistence requirements
## Using Agents in Tasks
Agents can be executed within tasks using the agent task type:
```yaml Basic Usage theme={"dark"}
tasks:
- id: analyze_content
type: agent
use: compozy/agents:content-moderator@1.0.0
with:
content: "{{ trigger.content }}"
```
```yaml Custom Configuration theme={"dark"}
tasks:
- id: market_analysis
type: agent
use: compozy/agents:market-analyst@1.0.0
config:
temperature: 0.4
max_tokens: 2000
with:
symbols: "{{ trigger.symbols }}"
timeframe: "1d"
```
```yaml Multiple Actions theme={"dark"}
tasks:
- id: research_task
type: agent
use: compozy/agents:researcher@1.0.0
actions:
- id: search
with:
query: "{{ trigger.topic }}"
- id: analyze
with:
content: "{{ actions.search.output }}"
- id: summarize
with:
analysis: "{{ actions.analyze.output }}"
```
When using agents in tasks:
* The agent's output is available as the task output
* Task error handling and retry mechanisms apply to the agent execution
* Agent configuration can be overridden at the task level
* Multiple agent actions can be executed sequentially
## Memory Integration
Agents can be configured to use memory defined at the workflow level:
```yaml Memory Definition theme={"dark"}
# Define memory in workflow
memory:
support_memory:
id: support_memory
vector:
use: compozy/vector:pg-vector
dimensions: 1536
chat_memory:
id: chat_memory
storage:
use: compozy/storage:postgres
vector:
use: compozy/vector:pinecone
dimensions: 1536
options:
lastMessages: 10
semanticRecall:
enabled: true
```
```yaml Agent Memory Usage theme={"dark"}
# Reference memory in agents
agents:
- id: support_agent
use: compozy/agents:support
memory: support_memory # Reference to workflow memory
- id: chat_agent
use: compozy/agents:chat
memory: chat_memory # Reference to workflow memory
```
```yaml Task Memory Access theme={"dark"}
tasks:
- id: support_task
type: agent
use: support_agent
with:
context: "{{ memory.support_memory.current_thread }}"
history: "{{ memory.support_memory.last_messages }}"
relevant: "{{ memory.support_memory.semantic_search }}"
```
## References
Learn about different types of agents
Available tools and integration
Memory overview
Complete agent configuration API