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

# Agents

> Register, list, update, and delete agents via the Python SDK

## register()

Register the current agent with MeshAI. Must be called before `start_heartbeat()` or `track_usage()`.

```python theme={null}
agent = client.register(
    framework="crewai",
    model_provider="openai",
    model_name="gpt-4o",
    description="Summarizes customer support tickets",
    team="support-team",
    tags={"env": "production", "version": "1.2.0"},
)
```

<ParamField path="framework" type="string" required>
  Agent framework: `crewai`, `langchain`, `autogen`, `openai`, `anthropic`, `custom`
</ParamField>

<ParamField path="model_provider" type="string">
  LLM provider: `openai`, `anthropic`, `google`, `nvidia`, `bedrock`
</ParamField>

<ParamField path="model_name" type="string">
  Model identifier (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
</ParamField>

<ParamField path="description" type="string">
  Human-readable description of what the agent does
</ParamField>

<ParamField path="team" type="string">
  Team or project that owns this agent (used for cost attribution)
</ParamField>

<ParamField path="tags" type="dict">
  Key-value metadata tags
</ParamField>

**Returns**: Agent object with `id`, `name`, `status`, and all metadata.

## list\_agents()

List all agents in your tenant.

```python theme={null}
agents = client.list_agents(
    status="healthy",
    framework="crewai",
    limit=50,
    offset=0,
)
```

<ParamField path="status" type="string">
  Filter by status: `healthy`, `degraded`, `down`, `unknown`
</ParamField>

<ParamField path="framework" type="string">
  Filter by framework
</ParamField>

<ParamField path="team" type="string">
  Filter by team
</ParamField>

<ParamField path="limit" type="integer" default="20">
  Number of results per page
</ParamField>

<ParamField path="offset" type="integer" default="0">
  Number of results to skip
</ParamField>

**Returns**: List of agent objects with pagination metadata.

## get\_agent()

Get a single agent by ID.

```python theme={null}
agent = client.get_agent("agt_abc123")
```

<ParamField path="agent_id" type="string" required>
  Agent ID
</ParamField>

**Returns**: Agent object.

```json theme={null}
{
  "id": "agt_abc123",
  "name": "production-summarizer",
  "description": "Summarizes customer support tickets",
  "framework": "crewai",
  "model_provider": "openai",
  "model_name": "gpt-4o",
  "environment": "production",
  "status": "healthy",
  "team": "support-team",
  "risk_level": "limited",
  "last_heartbeat": "2026-03-17T10:30:00Z",
  "created_at": "2026-03-01T08:00:00Z"
}
```

## update\_agent()

Update an agent's metadata.

```python theme={null}
updated = client.update_agent(
    "agt_abc123",
    description="Summarizes and categorizes support tickets",
    model_name="gpt-4o-mini",
    tags={"version": "1.3.0"},
)
```

<ParamField path="agent_id" type="string" required>
  Agent ID
</ParamField>

<ParamField path="description" type="string">
  Updated description
</ParamField>

<ParamField path="model_provider" type="string">
  Updated model provider
</ParamField>

<ParamField path="model_name" type="string">
  Updated model name
</ParamField>

<ParamField path="team" type="string">
  Updated team
</ParamField>

<ParamField path="tags" type="dict">
  Updated tags (merges with existing)
</ParamField>

**Returns**: Updated agent object.

## delete\_agent()

Delete an agent. The agent is removed from the active registry but remains in the audit trail.

```python theme={null}
client.delete_agent("agt_abc123")
```

<ParamField path="agent_id" type="string" required>
  Agent ID
</ParamField>

**Returns**: Confirmation object.

<Warning>
  Deleting an agent is irreversible. The agent's historical data (cost, anomalies, audit events) is preserved but the agent can no longer send heartbeats or telemetry.
</Warning>