> For the complete documentation index, see [llms.txt](https://underdogcowboy.gitbook.io/underdogcowboy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://underdogcowboy.gitbook.io/underdogcowboy-docs/basics/agents-in-underdog-cowboy.md).

# Agents in Underdog Cowboy

##

### Overview

Agents in the Underdog Cowboy system are intelligent entities designed to perform specific tasks, engage in dialogues, and assist users in various operations. These agents serve as intermediaries between users and Language Models (LLMs), encapsulating conversation context, specialized knowledge, and specific capabilities.

### Types of Agents

#### 1. User-Defined Agents

* Created through interactions in the [Timeline Editor](/underdogcowboy-docs/basics/timeline-editor.md)
* Stored as JSON files in the user's home directory (\~/.underdogcowboy/agents)
* Reflect personalized conversation patterns and knowledge

#### 2. Specialized Agents

* Pre-packaged with the Underdog Cowboy release
* Installed via pip along with the main package
* Designed for specific, advanced functionalities

#### 3. Regular Dialogs

* Stored in the same JSON format as agents
* May not have specific agent behaviors
* Useful for storing and reusing conversation patterns

### Agent Structure

Agents are represented by the `Agent` class, which includes:

* Unique identifier (ID)
* Name
* Associated filename and package
* Loaded content from JSON file
* Dialog manager for handling interactions

### Creating Agents

1. **Using Timeline Editor**
   * Launch with `timelineeditor` command
   * Engage in dialogue with an LLM
   * Save the interaction as an agent
2. **Manual JSON Creation**
   * Create a JSON file with required agent structure
   * Place in appropriate directory for loading

### Using Agents in Scripts

```python
from underdogcowboy import adm, your_agent_name

# Enable dialogue
adm | [your_agent_name]

# Send a message
response = your_agent_name >> "Your message here"
print(response)
```

### Interactive Development

Agents can be refined interactively:

1. Add `+adm` in your script to enter interactive mode
2. Engage in dialogue to test and improve agent responses
3. Use `resume` to continue script execution with updated behavior

### Advanced Features

* **Operator Overloading**: Use `>>` for sending messages
* **Dialog Manager Integration**: Agents work closely with the Dialog Manager for message handling
* **Dynamic Loading**: Agents are loaded dynamically, allowing for easy expansion and customization

### Best Practices

1. Start with a clear purpose for your agent
2. Use the [Timeline Editor](/underdogcowboy-docs/basics/timeline-editor.md) for initial creation and testing
3. Refine agents through interactive development in scripts
4. Regularly update and maintain your agents based on performance

### Conclusion

Agents in Underdog Cowboy provide a flexible and powerful way to interact with LLMs, enabling personalized, context-aware, and task-specific AI assistance. Whether using pre-built specialized agents or creating your own, the system offers a range of tools for developing and deploying intelligent agents in your projects.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://underdogcowboy.gitbook.io/underdogcowboy-docs/basics/agents-in-underdog-cowboy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.