Headless Fleet quickstart

Create your first agent and run it through the Headless Fleet API.

In this quickstart, you’ll authenticate against the Headless Fleet API, create an agent from code, and run it on a new thread.

Before you start

You’ll need:

• A LangSmith account (sign up here).
• A LangSmith API key.
• An OpenAI or Anthropic API key, added to your LangSmith workspace as a secret.

If you don’t already have a model API key configured in LangSmith, follow Steps 1 and 2 of the Fleet quickstart to create one and store it as OPENAI_API_KEY or ANTHROPIC_API_KEY before continuing.

1. Get your LangSmith API key

If you don’t already have one, follow the Create an API key guide. Save the key (it starts with lsv2_) somewhere safe.

Treat your LangSmith API key like a password. It carries the permissions of your account.

2. Verify your credentials

List the agents in your workspace to confirm authentication is working:

curl --request GET \
  --url {BASE_URL}/v1/fleet/agents \
  --header '{HEADER_NAME}: LANGSMITH_API_KEY'

A successful response returns a paginated list:

{
  "items": [],
  "next_cursor": null
}

If the list is empty, you’re ready to create your first agent.

3. Create your first agent

Send a POST request to /v1/fleet/agents with a name and a basic configuration:

curl --request POST \
  --url {BASE_URL}/v1/fleet/agents \
  --header '{HEADER_NAME}: LANGSMITH_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My first agent",
    "graph_id": "{GRAPH_ID}"
  }'

The response includes the new agent’s id. Save it for the next step.

{
  "id": "agt_...",
  "name": "My first agent",
  "status": "active"
}

graph_id selects which underlying graph runs your agent. Available graph IDs depend on your workspace configuration. Confirm with your LangSmith administrator or list available graphs in your deployment.

4. Create a thread

A thread holds the state of a conversation across one or more runs:

curl --request POST \
  --url {BASE_URL}/v1/fleet/threads \
  --header '{HEADER_NAME}: LANGSMITH_API_KEY'

Save the returned thread_id.

5. Run your agent

Stream a run on the thread, passing the agent_id from Step 3 and an input message:

curl --request POST \
  --url {BASE_URL}/v1/fleet/threads/{THREAD_ID}/runs/stream \
  --header '{HEADER_NAME}: LANGSMITH_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": "{AGENT_ID}",
    "input": {
      "messages": [{ "role": "user", "content": "Hello" }]
    }
  }'

The response streams events as the agent runs. When the stream completes, your agent has produced its first reply.

Next steps

API reference

Browse all endpoints and request schemas.

Add tools

Connect Slack, GitHub, Linear, and more.

Schedule and trigger runs

Run your agent on a schedule or in response to events.

Skills

Package reusable knowledge and actions for your agents.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.