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

# Managing Agents

> Create, configure, publish, version, and delete agents

# Managing Agents

Agents are the core building block of the Meibel platform. Each agent encapsulates a system prompt, model configuration, and optional datasources. This guide walks through the full lifecycle: creating, inspecting, updating, publishing, versioning, and deleting agents.

## Create an agent

Create a new agent definition by providing a name, description, and system prompt.

<CodeGroup>
  ```python Python theme={null}
  import os
  from meibel import MeibelClient
  from meibel.models import CreateAgentDefinitionRequest

  client = MeibelClient(api_key=os.environ["MEIBEL_API_KEY"])

  agent = client.agents.create_agent(body=CreateAgentDefinitionRequest(
      display_name="Research Assistant",
      description="Answers questions using uploaded knowledge bases",
      instructions="You are a helpful research assistant. Answer questions accurately and cite your sources.",
  ))

  print(agent.id, agent.display_name)
  ```

  ```typescript TypeScript theme={null}
  import { MeibelClient } from 'meibel';

  const client = new MeibelClient({ apiKey: process.env.MEIBEL_API_KEY });

  const agent = await client.agents.createAgent({
    displayName: 'Research Assistant',
    description: 'Answers questions using uploaded knowledge bases',
    instructions: 'You are a helpful research assistant. Answer questions accurately and cite your sources.',
  });

  console.log(agent.id, agent.displayName);
  ```

  ```go Go theme={null}
  import (
      "context"
      "fmt"
      "os"

      meibel "github.com/meibel-ai/meibel-go"
  )

  client := meibel.NewClient(meibel.WithAPIKey(os.Getenv("MEIBEL_API_KEY")))
  ctx := context.Background()

  agent, err := client.Agents.CreateAgent(ctx, meibel.CreateAgentDefinitionRequest{
      DisplayName:  "Research Assistant",
      Description:  "Answers questions using uploaded knowledge bases",
      Instructions: "You are a helpful research assistant. Answer questions accurately and cite your sources.",
  })
  if err != nil {
      log.Fatal(err)
  }

  fmt.Println(agent.ID, agent.DisplayName)
  ```

  ```bash CLI theme={null}
  meibel agents create --data '{
    "display_name": "Research Assistant",
    "description": "Answers questions using uploaded knowledge bases",
    "instructions": "You are a helpful research assistant. Answer questions accurately and cite your sources."
  }'
  ```
</CodeGroup>

The response includes the agent's `id`, `display_name`, `description`, `instructions`, and timestamps. Use the `id` for all subsequent operations.

## Get agent details

Retrieve the full configuration and metadata for an existing agent.

<CodeGroup>
  ```python Python theme={null}
  agent = client.agents.get_agent(agent_id="agent_123")

  print(agent.display_name)
  print(agent.instructions)
  print(agent.created_at)
  ```

  ```typescript TypeScript theme={null}
  const agent = await client.agents.getAgent('agent_123');

  console.log(agent.displayName);
  console.log(agent.instructions);
  console.log(agent.createdAt);
  ```

  ```go Go theme={null}
  agent, err := client.Agents.GetAgent(ctx, "agent_123")
  if err != nil {
      log.Fatal(err)
  }

  fmt.Println(agent.DisplayName)
  fmt.Println(agent.Instructions)
  fmt.Println(agent.CreatedAt)
  ```

  ```bash CLI theme={null}
  meibel agents get agent_123
  ```
</CodeGroup>

## Update an agent

Modify an agent's name, description, system prompt, or other configuration fields. Only the fields you include in the request body are changed.

<CodeGroup>
  ```python Python theme={null}
  from meibel.models import UpdateAgentDefinitionRequest

  updated = client.agents.update_agent(
      agent_id="agent_123",
      body=UpdateAgentDefinitionRequest(
          display_name="Research Assistant v2",
          instructions="You are an expert research assistant. Always cite sources with page numbers.",
      ),
  )

  print(updated.display_name)
  ```

  ```typescript TypeScript theme={null}
  const updated = await client.agents.updateAgent('agent_123', {
    displayName: 'Research Assistant v2',
    instructions: 'You are an expert research assistant. Always cite sources with page numbers.',
  });

  console.log(updated.displayName);
  ```

  ```go Go theme={null}
  updated, err := client.Agents.UpdateAgent(ctx, "agent_123", meibel.UpdateAgentDefinitionRequest{
      DisplayName:  "Research Assistant v2",
      Instructions: "You are an expert research assistant. Always cite sources with page numbers.",
  })
  if err != nil {
      log.Fatal(err)
  }

  fmt.Println(updated.DisplayName)
  ```

  ```bash CLI theme={null}
  meibel agents update agent_123 --data '{
    "display_name": "Research Assistant v2",
    "instructions": "You are an expert research assistant. Always cite sources with page numbers."
  }'
  ```
</CodeGroup>

## Publish an agent

Publishing creates an immutable snapshot of the agent's current configuration. Include a commit message to document what changed.

<CodeGroup>
  ```python Python theme={null}
  from meibel.models import PublishAgentDefinitionRequest

  published = client.agents.publish_agent(
      agent_id="agent_123",
      body=PublishAgentDefinitionRequest(
          commit_message="Improved citation formatting and added page-number references",
      ),
  )

  print(published.version)
  print(published.commit_message)
  ```

  ```typescript TypeScript theme={null}
  const published = await client.agents.publishAgent('agent_123', {
    commitMessage: 'Improved citation formatting and added page-number references',
  });

  console.log(published.version);
  console.log(published.commitMessage);
  ```

  ```go Go theme={null}
  published, err := client.Agents.PublishAgent(ctx, "agent_123", meibel.PublishAgentDefinitionRequest{
      CommitMessage: "Improved citation formatting and added page-number references",
  })
  if err != nil {
      log.Fatal(err)
  }

  fmt.Println(published.Version)
  fmt.Println(published.CommitMessage)
  ```

  ```bash CLI theme={null}
  meibel agents publish agent_123 --data '{
    "commit_message": "Improved citation formatting and added page-number references"
  }'
  ```
</CodeGroup>

<Note>
  Publishing does not affect the draft agent. You can continue editing the draft and publish again when ready.
</Note>

## List agent versions

Retrieve all published versions for an agent. Versions are returned in reverse chronological order.

<CodeGroup>
  ```python Python theme={null}
  for version in client.agents.list_agent_versions(agent_id="agent_123"):
      print(f"v{version.version}: {version.commit_message} ({version.published_at})")
  ```

  ```typescript TypeScript theme={null}
  for await (const version of client.agents.listAgentVersions('agent_123')) {
    console.log(`v${version.version}: ${version.commitMessage} (${version.publishedAt})`);
  }
  ```

  ```go Go theme={null}
  iter := client.Agents.ListAgentVersions(ctx, "agent_123")
  for iter.Next(ctx) {
      version := iter.Item()
      fmt.Printf("v%d: %s (%s)\n", version.Version, version.CommitMessage, version.PublishedAt)
  }
  if err := iter.Err(); err != nil {
      log.Fatal(err)
  }
  ```

  ```bash CLI theme={null}
  meibel agents list-agent-versions agent_123
  ```
</CodeGroup>

## Delete an agent

Permanently remove an agent and all its published versions. This action cannot be undone.

<CodeGroup>
  ```python Python theme={null}
  client.agents.delete_agent(agent_id="agent_123")
  ```

  ```typescript TypeScript theme={null}
  await client.agents.deleteAgent('agent_123');
  ```

  ```go Go theme={null}
  err := client.Agents.DeleteAgent(ctx, "agent_123")
  if err != nil {
      log.Fatal(err)
  }
  ```

  ```bash CLI theme={null}
  meibel agents delete agent_123
  ```
</CodeGroup>

<Warning>
  Deleting an agent removes all published versions and terminates any active sessions associated with it.
</Warning>