> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artaios.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Capabilities

> Explore tools, streaming, and other agent capabilities

Agents in AMAS can be enhanced with various capabilities to handle complex tasks. This guide covers all available capabilities and how to configure them.

## Tools

Tools extend agent capabilities by providing access to external systems, APIs, and computational resources. Only **ReAct agents** (`react_agent`) support tool calling.

> [!NOTE]
>
> We're actively working on integrating with the **Model Context Protocol (MCP)** to expand the available tools and enable seamless integration with external services.

### Available Tools

> **tavily\_search**
>
> **Web Search**
>
> Search engine optimized for comprehensive, accurate results from the web.
>
> *Configurable*

> **tavily\_extract**
>
> **Content Extraction**
>
> Extracts comprehensive content from web pages based on URLs.
>
> *Configurable*

> **google\_search**
>
> **Google Search**
>
> Gemini-grounded Google Search with AI-synthesized answers and citations.
>
> *Configurable*

> **calculator**
>
> **Calculator**
>
> Performs basic mathematical calculations safely.

> **randomizer**
>
> **Randomizer**
>
> Generates random integers within a configurable range for dynamic workflows.
>
> *Configurable*

> **wikipedia\_search**
>
> **Wikipedia Search**
>
> Search Wikipedia and get article summaries on any topic.

> **arxiv\_search**
>
> **ArXiv Search**
>
> Search academic papers on ArXiv.org across scientific fields.

> **youtube\_search**
>
> **YouTube Search**
>
> Search YouTube for videos and content.

> **python\_repl**
>
> **Python REPL**
>
> Execute Python code in a safe environment.

> **memory**
>
> **Memory Management**
>
> Explicitly save information to designated memory spaces for long-term retention.
>
> *Configurable*

> **schedule\_agent\_task**
>
> **Schedule Agent Task**
>
> Create scheduled tasks (cronjobs) for agents to run at specific times.

> **manage\_agent\_tasks**
>
> **Manage Agent Tasks**
>
> Query, update, enable/disable, or delete existing scheduled tasks.

### Configuring Tools

Tools can be added in two ways: **simple** (just the tool name) or **with configuration** (for tools that support it).

#### Simple Tool Configuration

Most tools can be added by just specifying their name:

```yaml theme={null}
agents:
  - name: "research_agent"
    agent_type: "react_agent"
    
    tools:
      - "wikipedia_search"
      - "arxiv_search"
      - "calculator"
    
    max_iterations: 10
```

#### Advanced Tool Configuration

Some tools support optional configuration for customization:

**Configurable Tools:**

* `tavily_search` - Web search with advanced options
* `tavily_extract` - Content extraction with format options
* `google_search` - Gemini model, temperature, and timeout options
* `randomizer` - Default min/max range
* `memory` - Specific memory modules to expose

```yaml theme={null}
agents:
  - name: "advanced_researcher"
    agent_type: "react_agent"
    
    tools:
      # Simple tools (no config)
      - "wikipedia_search"
      - "calculator"
      
      # Configured tools
      - name: "tavily_search"
        tool_type: "tavily_search"
        config:
          max_results: 10
          include_answer: true
          include_raw_content: "markdown"
          country: "US"
      
      - name: "tavily_extract"
        tool_type: "tavily_extract"
        config:
          format: "markdown"
    
    max_iterations: 10
```

### Tool Configuration Reference

> **tavily\_search Configuration**
>
> **Available options:**
>
> * `max_results` (integer, default: 5) - Maximum number of search results
> * `include_answer` (boolean, default: false) - Include a short answer to the query
> * `include_raw_content` (string, default: "markdown") - Include cleaned HTML content ("markdown" or "text")
> * `include_image_descriptions` (boolean, default: false) - Include image descriptions
> * `country` (string, optional) - Boost results from specific country (e.g., "US", "UK")
> * `auto_parameters` (boolean, default: false) - Enable automatic parameter configuration
> * `timeout` (integer, default: 30) - Request timeout in seconds

> **tavily\_extract Configuration**
>
> **Available options:**
>
> * `format` (string, default: "markdown") - Output format: "markdown" or "text"
> * `timeout` (integer, default: 30) - Request timeout in seconds

> **google\_search Configuration**
>
> **Available options:**
>
> * `model` (string, default: "gemini-2.5-flash") - Gemini model for search grounding
> * `temperature` (float, default: 0.7) - Sampling temperature (0.0-2.0)
> * `max_output_tokens` (integer, default: 8192) - Maximum response tokens
> * `timeout` (integer, default: 60) - Request timeout in seconds

> **randomizer Configuration**
>
> **Available options:**
>
> * `min_value` (integer, default: 0) - Default minimum value (inclusive)
> * `max_value` (integer, default: 100) - Default maximum value (inclusive)
>
> Runtime parameters can override these defaults per call.

> **memory Configuration**
>
> **Available options:**
>
> * `modules` (list of strings, optional) - List of memory module names to expose to this tool. When specified, only these modules are available. When omitted, all modules with `auto_save: false` are exposed.

### Human Approval on Tools

The object form of a tool entry also accepts `hitl_config`, which pauses the run for human approval before the tool executes:

```yaml theme={null}
persistent_state: true          # ← required when any tool uses HITL

agents:
  - name: "assistant"
    agent_type: "react_agent"
    tools:
      - "tavily_search"
      - name: "mail_send_email"
        tool_type: "mail_send_email"
        hitl_config:
          requires_human_approval: true
          confirmation_prompt: "Send this email?"
```

Many write-type integration tools (Mail, TwentyCRM, Jira, Scheduler) already pause by default, and some irreversible ones always do regardless of configuration.

> **[Human-in-the-Loop](https://docs.artaios.ai/amas/agent_config/human-in-the-loop.md)**
>
> The precedence rules, every `hitl_config` option, and how approvals are answered

### Tool Calling Configuration

**max\_iterations** `integer` (default: 10)

Maximum number of ReAct reasoning-action-observation cycles. Set directly on the agent (not in a nested object). Tool calling is always enabled for `react_agent` agents when tools are provided.

**Recommended values:**

* Simple tasks: 3-5 iterations
* Research tasks: 5-10 iterations
* Complex analysis: 10-15 iterations

> [!WARNING]
>
> Setting `max_iterations` too high can lead to excessive API calls and longer response times. Start with lower values and increase if needed.

### Tool Usage Examples

#### Web Search and Research

```yaml theme={null}
- name: "web_researcher"
  agent_type: "react_agent"
  
  tools:
    - "tavily_search"
    - "tavily_extract"
  
  max_iterations: 8
  
  prompt_config:
    system_prompt: |
      You are a research specialist with web search capabilities.
      
      When researching:
      1. Use tavily_search to find relevant sources
      2. Use tavily_extract to get detailed content from URLs
      3. Synthesize information from multiple sources
      4. Always cite your sources
```

#### Data Analysis with Calculator

```yaml theme={null}
- name: "data_analyst"
  agent_type: "react_agent"
  
  tools:
    - "calculator"
    - "tavily_search"
  
  max_iterations: 5
  
  prompt_config:
    system_prompt: |
      You are a data analyst with calculation capabilities.
      
      For numerical tasks:
      1. Break down complex calculations into steps
      2. Use the calculator tool for accuracy
      3. Show your work and reasoning
      4. Provide insights from the results
```

***

## Streaming

Streaming enables real-time delivery of agent responses, tool calls, and reasoning steps to end users.

### Streaming Configuration

**streaming\_config.enable\_streaming** `boolean` (default: true)

Enable streaming of agent responses

**streaming\_config.show\_output\_to\_user** `boolean` (default: true)

Stream agent text output to users in real-time

**streaming\_config.show\_tool\_to\_user** `boolean` (default: true)

Show tool calling events and results to users

**streaming\_config.show\_reasoning** `boolean` (default: false)

Show agent's internal reasoning and thought process. **This flag has a dual purpose**: when enabled on models that support thinking (currently Gemini and Vertex AI Anthropic models), it also activates the model's internal reasoning mode, sending `enable_thinking=True` to the provider. The thinking content is then streamed via `ThinkingStart`, `ThinkingContent`, and `ThinkingEnd` events. *(Note: This field is system-managed and controlled by the platform UI, so it will be automatically stripped from LLM-generated configs).*

**streaming\_config.show\_memory** `boolean` (default: true)

Show memory query events to users. Controls visibility of `MemoryCall*` events emitted during memory retrieval operations.

**streaming\_config.send\_preview\_snippet** `boolean` (default: false)

Generate and send an LLM-powered agent introduction snippet before the main response. When enabled, the agent produces a brief preview of what it's about to do, streamed via `AgentIntroductionStart`, `AgentIntroductionContent`, and `AgentIntroductionEnd` events. *(Note: This field is system-managed and controlled by the platform UI, so it will be automatically stripped from LLM-generated configs).*

**streaming\_config.main\_chatbox** `boolean` (default: false)

Identifies whether this is the main chatbox agent. Used by the frontend to determine which agent's output should be rendered in the primary chat area. Propagated in agent introduction events. *(Note: This field is system-managed and controlled by the platform UI, so it will be automatically stripped from LLM-generated configs).*

### Streaming Examples

#### Standard User-Facing Streaming

```yaml theme={null}
streaming_config:
  enable_streaming: true
  show_output_to_user: true
  show_tool_to_user: true
  show_reasoning: false
  show_memory: true
```

**User sees:**

* ✅ Agent responses (streaming)
* ✅ Tool calls and results
* ✅ Memory retrieval events
* ❌ Internal reasoning

#### Development/Debug Mode

```yaml theme={null}
streaming_config:
  enable_streaming: true
  show_output_to_user: true
  show_tool_to_user: true
  show_reasoning: true
  show_memory: true
```

**User sees:**

* ✅ Agent responses (streaming)
* ✅ Tool calls and results
* ✅ Internal reasoning steps (also enables model thinking for Gemini)
* ✅ Memory retrieval events

> [!TIP]
>
> Enable `show_reasoning: true` during development to understand how agents make decisions. On models with thinking support (like Gemini or Vertex AI Anthropic), this also activates the model's built-in thinking mode, providing deeper insight into the reasoning process.

#### Main Chatbox Agent with Preview

```yaml theme={null}
streaming_config:
  enable_streaming: true
  show_output_to_user: true
  show_tool_to_user: true
  send_preview_snippet: true
  main_chatbox: true
```

**User sees:**

* ✅ Agent introduction snippet (preview of what it will do)
* ✅ Agent responses (streaming, rendered in primary chat area)
* ✅ Tool calls and results

#### Background Processing

```yaml theme={null}
streaming_config:
  enable_streaming: false
  show_output_to_user: false
  show_tool_to_user: false
```

**Use case:** Internal agents in supervisor architectures that process data without user interaction.

### Streaming Events

When streaming is enabled, the system emits these event types:

> **Text Message Events**
>
> * `TextMessageStart` - Agent begins generating a response (includes backend-generated message ID)
> * `TextMessageContent` - Streaming content chunks (delta text)
> * `TextMessageEnd` - Response generation complete

> **Thinking Events (show\_reasoning)**
>
> * `ThinkingStart` - Agent begins reasoning (only for models with thinking support)
> * `ThinkingContent` - Streaming thinking/reasoning chunks
> * `ThinkingEnd` - Reasoning complete
>
> Only emitted when `show_reasoning: true` and the model supports thinking (currently Gemini and Vertex AI Anthropic models).

> **Run Events**
>
> * `RunStarted` - Agent execution begins
> * `RunFinished` - Agent execution completes successfully
> * `RunError` - Agent execution encounters an error

> **LLM Events (tracing only)**
>
> * `LLMCallStarted` - LLM API call initiated (model, provider, temperature)
> * `LLMCallCompleted` - LLM call finished (includes token usage, cost, duration)
> * `LLMCallError` - LLM call failed

> **Tool Events (show\_tool\_to\_user)**
>
> * `ToolCallStart` - Tool execution begins (tool name, agent name)
> * `ToolCallArgs` - Tool argument data (streamed)
> * `ToolCallResult` - Tool execution result with content
> * `ToolCallEnd` - Tool execution complete
> * `ToolCallError` - Tool execution failed (AI continues processing)

> **Knowledge Base Events**
>
> * `KnowledgeBaseCallStart` - KB retrieval begins
> * `KnowledgeBaseCallArgs` - Query and config details
> * `KnowledgeBaseCallResult` - Retrieved results
> * `KnowledgeBaseCallEnd` - Retrieval complete
> * `KnowledgeBaseCallError` - Retrieval failed

> **Memory Events (show\_memory)**
>
> * `MemoryCallStart` - Memory query begins
> * `MemoryCallResult` - Retrieved memory items
> * `MemoryCallEnd` - Memory query complete
> * `MemoryCallError` - Memory query failed

> **Agent Introduction Events (send\_preview\_snippet)**
>
> * `AgentIntroductionStart` - Introduction snippet begins
> * `AgentIntroductionContent` - Introduction content
> * `AgentIntroductionEnd` - Introduction complete

***

## Knowledge Base Integration

Agents can access knowledge bases to retrieve domain-specific information and documents. Both **LLM agents** and **ReAct agents** support knowledge base integration.

> [!TIP]
>
> For comprehensive knowledge base configuration details, see the [Knowledge Base Setup](https://docs.artaios.ai/amas/agent_config/knowledge-base-setup.md) guide.

### Available Knowledge Base Types

> **milvus**
>
> **Milvus Vector Database**
>
> Production-ready vector database with dense vector semantic search and multi-tenancy support.

> [!NOTE]
>
> Additional vector database integrations will be supported in future releases.

### Configuration

Add knowledge bases directly to agent configuration:

```yaml theme={null}
agents:
  - name: "knowledge_agent"
    agent_type: "llm_agent"  # or react_agent
    
    knowledge_bases:
      - name: "company_docs"
        knowledge_base_type: "milvus"
        id: "kb_123"
        enabled: true
        config:
          top_k: 10
          strategy: "dense"
          search_ef: 64
```

### Configuration Reference

> **Knowledge Base Instance Fields**
>
> **Required fields:**
>
> * `name` (string) - Instance identifier (alphanumeric, hyphens, underscores only)
> * `knowledge_base_type` (string) - `"milvus"` or `"uknow"`
>
> **Optional fields:**
>
> * `enabled` (boolean, default: true) - Toggle KB on/off without removing it
> * `id` (string, optional) - KnowledgeBase model ID (for Milvus DB lookup)
> * `config` (object, default: {}) - Adapter-specific retrieval parameters
> * `description` (string, optional) - Human-readable description

> **Milvus config Fields**
>
> * `top_k` (integer, default: 10) - Number of results to return (1-1000)
> * `strategy` (string, default: "dense") - Search strategy: `"dense"`, `"hybrid"`, `"bm25"`, `"hybrid_rrf"`
> * `search_ef` (integer, optional) - HNSW search parameter (higher = more accurate but slower)
> * `score_threshold` (float, optional) - Minimum similarity score (0.0-1.0)
> * `offset` (integer, default: 0) - Number of results to skip for pagination
> * `embedding_provider` (string, default: "mistral") - `"mistral"`, `"azure_openai"`, or `"telekom_otc"`
> * `embedding_model` (string, default: "mistral-embed") - Embedding model name
> * `query_model` (string, optional) - LLM model for query expansion
> * `max_num_query_expansions` (integer, default: 0) - Number of expanded queries (0-5)
> * `filter_expression` (string, optional) - Raw Milvus filter expression
> * `filters` (object, optional) - Haystack-style metadata filters

> **UKnow config Fields**
>
> * `username` (string, required) - Cloud storage account email
> * `drive_key` (string, required) - Storage type: `"SP"` (SharePoint), `"ONEDRIVEP"` (OneDrive), `"GOOGLEDRIVE"`, `"CONFLUENCE"`
> * `path_filter` (string, default: "") - Restrict search to folder path
> * `drive_ids` (list of strings, default: \[]) - Specific drive IDs to search
> * `query_model` (string, optional) - LLM for query processing
> * `max_num_query_expansions` (integer, default: 0) - Number of expanded queries
> * `search_options.search_type` (string, default: "similarity") - `"similarity"`, `"similarity_score_threshold"`, `"mmr"`
> * `search_options.fetch_k` (integer, default: 5) - Number of results
> * `search_options.lambda_mult` (float, default: 0.5) - MMR lambda multiplier

***

## LLM Configuration

Fine-tune language model behavior for different use cases.

### Model Selection

```yaml theme={null}
llm_config:
  model: "gpt-4o"  # Provider auto-detected from model name
```

**Available models** (see [Available Models](https://docs.artaios.ai/amas/agent_config/types_config/model-selection.md) for the full list):

* `gpt-4o` - Azure OpenAI (text + image)
* `gemini-2.5-flash` / `gemini-2.5-pro` - Google Gemini (text, image, audio, video + thinking)
* `gemini-3-flash` / `gemini-3.1-flash-lite` / `gemini-3.1-pro` - Gemini 3 & 3.1 (text, image, audio, video + thinking, 64K output)
* `claude-opus-4-6` / `claude-sonnet-4-6` - Vertex AI Anthropic (text, image + thinking)
* `mistral-large` / `mistral-small` - Mistral AI (text + image)
* `Llama-3.3-70B` / `Qwen3-30B` / `claude-sonnet-4` - Telekom OTC

### Temperature Control

Temperature controls the randomness and creativity of responses:

```yaml theme={null}
llm_config:
  temperature: 0.7  # Range: 0.0 - 2.0
```

**Temperature Guidelines:**

| Temperature | Use Case | Example |
| - | - | - |
| 0.0 - 0.3 | Factual, deterministic | Data analysis, fact retrieval |
| 0.4 - 0.7 | Balanced | General conversation, Q\&A |
| 0.8 - 1.2 | Creative | Content writing, brainstorming |
| 1.3 - 2.0 | Highly creative | Creative writing, poetry |

> [!TIP]
>
> For most applications, a temperature of 0.7 provides a good balance between consistency and natural variation.

### Token Limits

```yaml theme={null}
llm_config:
  max_tokens: 2000
```

Control the maximum length of generated responses:

* **Short responses**: 500-1000 tokens
* **Standard responses**: 1000-2000 tokens
* **Long-form content**: 2000-4000 tokens

> [!WARNING]
>
> Higher token limits increase API costs and response times. Set appropriate limits based on your use case.

***

## Advanced Capabilities

### Multi-Agent Coordination

Supervisor agents coordinate multiple specialized agents:

```yaml theme={null}
- name: "supervisor"
  agent_type: "supervisor"
  
  # Agents under supervision
  supervised_agents:
    - "researcher"
    - "analyst"
    - "writer"
  
  # Coordination behavior
  return_to_supervisor: true
  max_handoffs: 15
  
  prompt_config:
    system_prompt: |
      Coordinate the team by delegating tasks to specialists.
      Evaluate their work and decide on next steps.
```

> [!TIP]
>
> Supervisors can coordinate both LLM agents and ReAct agents, creating hybrid teams with diverse capabilities.

### Agent Handoffs

In supervisor architectures, agents can hand off tasks to each other. Define the coordination strategy in `prompt_config.system_prompt`:

```yaml theme={null}
prompt_config:
  system_prompt: |
    You coordinate a research team.
    
    Workflow:
    1. Delegate research to research_agent
    2. Send findings to analysis_agent
    3. Have writer_agent create the final report
    
    Use transfer tools to hand off between agents.
```

***

## Capability Combinations

### Research + Analysis Agent

```yaml theme={null}
- name: "research_analyst"
  agent_type: "react_agent"
  
  tools:
    - "tavily_search"
    - "tavily_extract"
    - "calculator"
  
  max_iterations: 12
  
  llm_config:
    model: "gpt-4o"
    temperature: 0.2  # Low for factual accuracy
    max_tokens: 3000
  
  streaming_config:
    enable_streaming: true
    show_output_to_user: true
    show_tool_to_user: true
    show_reasoning: true
  
  knowledge_bases:
    - name: "research_db"
      knowledge_base_type: "milvus"
      enabled: true
  
  prompt_config:
    system_prompt: |
      You are a research analyst with comprehensive capabilities.
      
      Your tools:
      - Web search for current information
      - Content extraction from URLs
      - Calculator for numerical analysis
      - Knowledge base for historical context
      
      Approach:
      1. Search knowledge base for existing information
      2. Use web search for current data
      3. Extract detailed content from sources
      4. Perform calculations as needed
      5. Synthesize comprehensive analysis
```

### Creative Writing Agent

```yaml theme={null}
- name: "creative_writer"
  agent_type: "llm_agent"
  
  llm_config:
    model: "gpt-4o"
    temperature: 1.0  # High for creativity
    max_tokens: 4000
  
  streaming_config:
    enable_streaming: true
    show_output_to_user: true
  
  prompt_config:
    system_prompt: |
      You are a creative writer specializing in engaging, 
      well-structured content.
      
      Your writing style:
      - Clear and engaging
      - Well-organized with proper structure
      - Appropriate tone for the audience
      - Creative but professional
```

***

## Best Practices

### Tool Selection

> [!TIP]
>
> **Principle of Least Privilege**: Only provide tools that the agent actually needs. More tools increase complexity and potential for errors.

> [!TIP]
>
> Test agents with minimal tools first, then add more as needed.

### Streaming Configuration

> [!TIP]
>
> **Production**: Disable `show_reasoning` for end users. Enable for internal monitoring and debugging.

> [!TIP]
>
> **User Experience**: Always enable `show_output_to_user` for user-facing agents to provide real-time feedback.

### Performance Optimization

> [!TIP]
>
> **Max Iterations**: Start with 5-7 iterations. Monitor actual usage and adjust based on task complexity.

> [!TIP]
>
> **Token Limits**: Set realistic `max_tokens` based on expected response length to control costs.

### System Prompts

> [!TIP]
>
> **Tool Instructions**: When agents have tools, explicitly describe when and how to use them in the system prompt.

> [!TIP]
>
> **Capability Awareness**: Make agents aware of their capabilities and limitations in the system prompt.

***

## Troubleshooting

> **Agent not using tools**
>
> **Possible causes:**
>
> * Agent type is not `react_agent` (only ReAct agents support tools)
> * System prompt doesn't mention tool usage
> * `max_iterations` is too low
> * Tools are not registered in the agent registry
>
> **Solution:** Ensure `agent_type: "react_agent"`, update `prompt_config.system_prompt` to encourage tool use, and increase `max_iterations`.

> **Infinite tool calling loops**
>
> **Cause:** Agent repeatedly calls tools without reaching a conclusion
>
> **Solution:** Lower `max_iterations` and improve system prompt to guide the agent toward conclusions.

> **Streaming not working**
>
> **Possible causes:**
>
> * `enable_streaming` is false
> * `show_output_to_user` is false
> * Network/connection issues
>
> **Solution:** Verify streaming configuration and check network connectivity.

> **Knowledge base not returning results**
>
> **Possible causes:**
>
> * Knowledge base not properly configured
> * `enabled` is false
> * Empty or unindexed knowledge base
>
> **Solution:** Verify knowledge base configuration and ensure data is properly indexed.

***

## Next Steps

> **[YAML Configuration](https://docs.artaios.ai/amas/yaml-configuration.md)**
>
> Complete YAML configuration reference

> **[Agent Types](https://docs.artaios.ai/amas/agent_config/types_config/agent-types.md)**
>
> Learn about different agent types

> **[API Reference](https://docs.artaios.ai/api-reference/introduction.md)**
>
> Explore the API for programmatic access


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.