> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alfa.boosted.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server.

# Create and manage agents (Deprecated)

Alfa agents are the core building blocks of your AI-powered workflow. In this guide, we'll walk through the complete lifecycle of an agent using our API - from creation to retrieving results.

## Creating your first agent

Creating an agent is simple - you just need to provide a clear prompt that describes what you want the agent to do.

```python
import requests

BASE_URL = "https://alfa.boosted.ai/client"
API_KEY = "YOUR_API_KEY_HERE"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

def create_agent(prompt):
    """Create a new agent with the specified prompt."""
    url = f"{BASE_URL}/agent/create-agent"
    payload = {"prompt": prompt}
    
    response = requests.post(url, headers=headers, json=payload)
    
    if response.status_code == 201:
        data = response.json()
        agent_id = data.get("agent_id")
        print(f"Success! Agent created with ID: {agent_id}")
        return agent_id
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None

# Create an agent to analyze Tesla's stock performance
agent_id = create_agent("What was TSLA's close price on Feb 1, 2023 and how does it compare to recent performance?")
```

> **Tip**
>
> For complex analyses, you can include placeholders like `{doc}` in your prompt to reference custom documents. See our [Custom Documents](/guides/deprecated/knowledge-base/custom-documents#creating-agents-with-custom-documents) guide for details.

### Example: Creating an agent for comprehensive price target analysis

#### Define your analysis needs

Determine what specific market data you want to analyze

#### Formulate your prompt

Create a clear prompt that specifies exactly what you need:

```python
comprehensive_prompt = """
Show a line graph of Target Price Consensus Mean over the past year for Apple. Then show current
Target Price Consensus High and Target Price Consensus Low in a table. Finally, in a new section,
get all news developments for the target company, then get the articles associated with those developments.
Pass the articles to the text to table tool and extract all the analysts that have given ratings and their
price targets, using the columns research firm, price target, date, and buy/sell recommendation.
"""
```

#### Create the agent

```python
# Create price target analysis agent
analysis_agent_id = create_agent(comprehensive_prompt)

print(f"Your price target analysis agent is being created with ID: {analysis_agent_id}")
```

## Monitoring agent status

After creating an agent, it will start processing your request in the background. You can check its status to know when it's done.

```python
import time

def get_agent_status(agent_id):
    """Check if an agent has completed its processing."""
    url = f"{BASE_URL}/agent/status?agent_id={agent_id}"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        status = data.get("status")
        print(f"Agent status: {status}")
        return status
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None

# Poll until the agent is done
status = ""
while status != "COMPLETE":
    status = get_agent_status(agent_id)
    if status in ["ERROR", "CANCELLED", "NO_RESULTS_FOUND"]:
        print(f"Agent encountered an issue: {status}")
        break
    if status != "COMPLETE":
        print("Agent still working... waiting 10 seconds")
        time.sleep(10)
```

The agent can be in one of the following states:

* `NOT_STARTED`: The agent has been created but hasn't begun processing
* `RUNNING`: The agent is actively working on your request
* `COMPLETE`: The agent has finished successfully
* `ERROR`: The agent encountered an error during processing
* `CANCELLED`: The processing was stopped before completion
* `NO_RESULTS_FOUND`: The agent completed but couldn't find relevant results

## Retrieving agent output

Once your agent has completed its work, you can retrieve the output.

```python
def get_agent_output(agent_id):
    """Retrieve the results from a completed agent."""
    url = f"{BASE_URL}/get-agent-output/{agent_id}"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None

# Get the agent's findings
output = get_agent_output(agent_id)

# Process the outputs
if output and "outputs" in output:
    for item in output["outputs"]:
        output_type = item["output"]["output_type"]
        
        if output_type == "text":
            print("Text output:", item["output"]["val"])
        elif output_type == "table":
            print("Table output with columns:", [col["name"] for col in item["output"]["columns"]])
        elif output_type == "graph":
            print(f"Graph output: {item['output']['title']} ({item['output']['graph']['graph_type']} graph)")
```

Agent outputs can be of different types:

* `text`: Plain text analysis and explanations
* `table`: Structured data in tabular format
* `graph`: Visual representation of data as a line, bar, or pie chart

### Example: Processing different output types

#### Get the agent output

First, fetch the agent's completed analysis

#### Process by output type

Handle different output formats appropriately:

```python
# Get the comprehensive analysis results
results = get_agent_output(agent_id)

if results and "outputs" in results:
    for i, item in enumerate(results["outputs"]):
        output_data = item["output"]
        output_type = output_data["output_type"]
        
        print(f"\n--- Output {i+1} ({output_type}) ---")
        
        if output_type == "text":
            # Save the text analysis to a file
            with open(f"analysis_{i+1}.txt", "w") as f:
                f.write(output_data["val"])
            print(f"Text analysis saved to analysis_{i+1}.txt")
            
        elif output_type == "table":
            # Export the table to CSV
            import csv
            
            columns = [col["name"] for col in output_data["columns"]]
            with open(f"table_{i+1}.csv", "w", newline="") as f:
                writer = csv.writer(f)
                writer.writerow(columns)
                writer.writerows(output_data["rows"])
            print(f"Table data exported to table_{i+1}.csv")
            
        elif output_type == "graph":
            # Just print info about the graph (in a real app, you might render it)
            graph_type = output_data["graph"]["graph_type"]
            title = output_data["title"]
            print(f"Graph: {title} ({graph_type})")
```

## Managing your agents

### Getting a specific agent

To retrieve basic details about a specific agent:

```python
def get_agent(agent_id):
    """Get metadata for a specific agent."""
    url = f"{BASE_URL}/agent/get-agent/{agent_id}"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Agent Name: {data.get('agent_name')}")
        print(f"Created: {data.get('created_at')}")
        print(f"Description: {data.get('agent_description')}")
        return data
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None

# Get details for a specific agent
agent_details = get_agent(agent_id)
```

### Example: Finding an agent by ID

#### Retrieve agent details

Get information about a specific agent you've created:

```python
# Look up an agent by its ID
agent_id = "ff39b720-8179-4e7d-9f4c-b5e9a35fb8d2"
agent_info = get_agent(agent_id)

if agent_info:
    print(f"\nAgent: {agent_info['agent_name']}")
    print(f"Created: {agent_info['created_at']}")
    print(f"Description: {agent_info.get('agent_description', 'No description')}")
else:
    print("Agent not found or access denied")
```

### Viewing all your agents

To get a list of all agents you've created and their basic details:

```python
def get_all_agents():
    """List all available agents."""
    url = f"{BASE_URL}/agent/get-all-agents"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        return data.get("agents", [])
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return []

# Display all your agents
agents = get_all_agents()
for agent in agents:
    print(f"ID: {agent['agent_id']}")
    print(f"Name: {agent['agent_name']}")
    print(f"Created: {agent['created_at']}")
    print("---")
```

### Example: Finding agents by pattern matching

#### Get all agents

First, retrieve the list of all your agents

#### Filter by criteria

Search for agents that match certain patterns:

```python
# Get all available agents
all_agents = get_all_agents()

# Filter agents by name pattern
earnings_agents = [a for a in all_agents if "earnings" in a["agent_name"].lower()]
recent_agents = [a for a in all_agents if a["created_at"] > "2023-10-01"]

# Display filtered results
print(f"\nFound {len(earnings_agents)} earnings-related agents:")
for agent in earnings_agents:
    print(f"- {agent['agent_name']} (ID: {agent['agent_id']})")

print(f"\nFound {len(recent_agents)} agents created since October 2023:")
for agent in recent_agents:
    print(f"- {agent['agent_name']} (created: {agent['created_at']})")
```

## Next steps

Now that you understand how to create and manage agents, you can:

* Learn how to [schedule and automate your agents](/guides/deprecated/scheduling-agents/schedule-and-automate-agents) to run on a custom schedule
* Explore using [custom documents](/guides/deprecated/knowledge-base/custom-documents) with your agents

> **Tip**
>
> For production systems, always implement proper error handling and consider using exponential backoff for status polling to avoid rate limiting.