Quickstart
In shortScaffold a support agent with 10xgraph init, chat with it in the playground, call the API with curl and TypeScript, turn on JWT auth and generate the Docker files.
- 10 min read
- 12 sections
- Updated
- v1.0.0
- Markdown
To build your first 10xGraph agent, scaffold a project with 10xgraph init, give the agent two tools, and start it with 10xgraph dev. You chat with it in the playground, call the API with curl, continue a thread, turn on JWT auth and watch a second user get 404 on the first user’s thread, call it from TypeScript, and write the Dockerfile.
You need Python 3.12 or newer and an API key for your chosen model provider (Google, OpenAI, or Anthropic). The TypeScript step also needs Node.js 20 or newer.
Install the packages
Choose your model provider and install the matching extra:
Google Gemini
pip install "10xgraph[google-genai]" "10xgraph-api[jwt]"OpenAI
pip install "10xgraph[openai]" "10xgraph-api[jwt]"Anthropic
pip install "10xgraph[anthropic]" "10xgraph-api[jwt]"The 10xgraph package is the framework. The 10xgraph-api package adds the server and the 10xgraph CLI, and its jwt extra installs PyJWT for the auth step below. The provider extra (google-genai, openai, or anthropic) lets 10xGraph call your chosen model. For details on API keys and other providers, see Installation.
Scaffold with 10xgraph init
Create an empty folder and run 10xgraph init in it. Init writes into the current directory.
mkdir support-agent && cd support-agent
10xgraph initIn Quick setup, init asks three questions: “Which setup?” (choose Quick), “What is your agent name?” and “Which AI provider?”. To skip the prompts, pass the answers as flags:
10xgraph init --mode quick --name support-agent --provider googleInit writes six files:
support-agent/
├── .env.example
├── .gitignore
├── 10xgraph.json
├── requirements.txt
└── graph/
├── __init__.py
└── agent.py10xgraph.json is the server config. Init writes this:
{
"agent": "graph.agent:app",
"env": ".env",
"auth": null,
"thread_name_generator": null,
"ag_ui": {
"enabled": false
},
"websocket": {
"enabled": false
}
}The agent value graph.agent:app means the app variable in graph/agent.py. The server loads and compiles it once at startup. env names the file the server reads for environment variables, and "auth": null leaves the server open for now. graph/agent.py is a working ReactAgent with a sample weather tool, compiled with an InMemoryCheckpointer. Quick setup is the fastest path to a running agent. Full setup also adds storage, API security, evals and tests (see Project structure).
Init does not read your key. Copy .env.example to .env and fill in the key for your provider. The file lists one variable: GOOGLE_API_KEY, OPENAI_API_KEY or ANTHROPIC_API_KEY.
cp .env.example .envSet the key before you start the server, because the agent module creates the provider client when it loads. .gitignore already excludes .env and keeps .env.example.
Make it a support agent
Replace the contents of graph/agent.py with the two order tools. Tools are plain Python functions. Their docstrings and type hints become the schema that the model sees, so write them clearly.
from dotenv import load_dotenv
from tenxgraph.prebuilt.agent import ReactAgent
from tenxgraph.storage.checkpointer import InMemoryCheckpointer
load_dotenv()
def lookup_order(order_id: str) -> dict:
"""Look up an order by id and return its status and total."""
return {"order_id": order_id, "status": "delivered", "total": 59.0}
def refund_order(order_id: str, amount: float) -> str:
"""Refund an order. This moves money, so it must run once per request."""
return f"Refunded {amount:.2f} for order {order_id}"
react_agent = ReactAgent(
model="gemini-2.5-flash",
provider="google",
system_prompt=[
{
"role": "system",
"content": "You are a concise support agent for an online shop.",
}
],
tools=[lookup_order, refund_order],
)
app = react_agent.compile(checkpointer=InMemoryCheckpointer())Keep the model and provider lines that init wrote for your provider. Init writes model="gpt-4o-mini" with provider="openai", and model="claude-sonnet-5-5" with provider="anthropic".
ReactAgent builds a standard reason-and-act graph for you: an agent node that calls the model, a tool node that runs tools, and conditional routing between them. compile() returns a CompiledGraph, the object the server loads.
Run it with 10xgraph dev
10xgraph devThe terminal shows the server address and then opens the playground:
✓ Ready to serve: 10xGraph runtime configured successfully
API http://127.0.0.1:8000
Docs http://127.0.0.1:8000/docs
Reload enabledThe server listens on 127.0.0.1:8000 and reloads when your files change. Plain 10xgraph dev also opens the hosted playground in your browser, at a URL like https://play.10xgraph.com?backendUrl=http%3A%2F%2F127.0.0.1%3A8000. On the Connect page the backend URL is filled in and the auth mode is None, which matches "auth": null. Chrome asks once for permission to reach your local server; click Allow. Then open Chat and send “Where is order 1042?”. The reply streams in and the tool calls appear inline. Thread Inspector lists the saved threads and their messages. See Playground for every page.
The rest of this page uses curl, so you can start the server without the browser:
10xgraph dev --no-openUse --host 0.0.0.0 to accept connections from other machines and --port to use a different port.
Call the API
In a second terminal, invoke the agent with curl. A message’s content is a list of typed blocks, not a string.
curl -X POST http://127.0.0.1:8000/v1/graph/invoke \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": [{"type": "text", "text": "Where is order 1042?"}]
}
]
}'The response holds data (the result) and metadata (request id and timestamp). data.messages lists the user message, the tool call, the tool result and the final reply, in order (fields such as message_id, timestamp and usages are left out here):
{
"data": {
"messages": [
{"role": "user", "content": [{"type": "text", "text": "Where is order 1042?"}]},
{"role": "assistant", "content": [{"type": "tool_call", "id": "call_1", "name": "lookup_order", "args": {"order_id": "1042"}}]},
{"role": "tool", "content": [{"type": "tool_result", "call_id": "call_1", "name": "lookup_order", "output": [{"order_id": "1042", "status": "delivered", "total": 59.0}], "is_error": false}]},
{"role": "assistant", "content": [{"type": "text", "text": "Order 1042 is delivered. The total is $59.00."}]}
],
"state": null,
"context": null,
"summary": null,
"meta": {"is_new_thread": true, "thread_id": "7f3c2a10-5b1e-4c9a-9d2e-1a2b3c4d5e6f"}
},
"metadata": {
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-11-15T12:30:45.123456",
"message": "OK"
}
}The reply is the last item in data.messages, and its wording varies by model. To watch the run as it happens, call /v1/graph/stream. Use -N so curl prints each line as it arrives:
curl -N -X POST http://127.0.0.1:8000/v1/graph/stream \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": [{"type": "text", "text": "Where is order 1042?"}]
}
]
}'The body is newline-delimited JSON, one chunk per line, not SSE. These are a few of the lines, trimmed to the main fields:
{"event": "message", "message": {"role": "user", "content": [{"type": "text", "text": "Where is order 1042?"}]}, "thread_id": "7f3c2a10-...", "run_id": "...", "metadata": {"status": "invoking_graph", "is_new_thread": true}}
{"event": "message", "message": {"role": "assistant", "content": [{"type": "tool_call", "name": "lookup_order", "args": {"order_id": "1042"}}]}, "thread_id": "7f3c2a10-...", "run_id": "..."}
{"event": "message", "message": {"role": "assistant", "delta": true, "content": [{"type": "text", "text": "Order 1042 is delivered."}]}, "thread_id": "7f3c2a10-...", "run_id": "..."}
{"event": "updates", "data": {"status": "done"}, "thread_id": "7f3c2a10-...", "run_id": "..."}Tool activity arrives as ordinary message chunks, and a stream that finishes without an error ends with an updates chunk whose data is {"status": "done"}. See Invoke and stream for every event type.
Continue the thread and read it back
Copy data.meta.thread_id from the invoke response and send it as config.thread_id on the next request. The agent still has the order it looked up, so it can refund it:
curl -X POST http://127.0.0.1:8000/v1/graph/invoke \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": [{"type": "text", "text": "Refund order 1042 for 59.00"}]
}
],
"config": {"thread_id": "7f3c2a10-5b1e-4c9a-9d2e-1a2b3c4d5e6f"}
}'The agent calls refund_order, and the last message confirms it. List the threads the server has saved, then read one back:
curl http://127.0.0.1:8000/v1/threads
curl http://127.0.0.1:8000/v1/threads/7f3c2a10-5b1e-4c9a-9d2e-1a2b3c4d5e6f/messagesEach entry in data.threads is a thread record:
{"thread_id": "7f3c2a10-5b1e-4c9a-9d2e-1a2b3c4d5e6f", "thread_name": null, "user_id": "anonymous", "metadata": null, "updated_at": "2026-11-15T12:31:02.512345", "run_id": null}data.messages on the second call holds the messages from both turns, with has_more, offset and limit beside it. The user_id is anonymous because the server is open. The next step changes that.
Turn on auth and see isolation
The server so far is open: anyone who can reach it can read any thread. Turn on JWT in 10xgraph.json by changing one line:
"auth": "jwt"Set a signing secret in the shell that starts the server. JWT_ALGORITHM defaults to HS256, and for HS algorithms the secret must be at least 32 bytes. Then stop the server with Ctrl+C and start it again:
export JWT_SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"
10xgraph dev --no-openThe server logs Authentication is DISABLED while auth is null, and refuses to load without JWT_SECRET_KEY once it is "jwt". Because InMemoryCheckpointer lives in the server process, the restart also clears the threads from the earlier steps.
In a second terminal, in the same project folder and with JWT_SECRET_KEY exported there too, sign a token for each of two users. In a real system your login service does this.
import os
import time
import jwt # PyJWT
secret = os.environ["JWT_SECRET_KEY"]
algorithm = os.environ.get("JWT_ALGORITHM", "HS256")
for user_id in ("alice", "bob"):
token = jwt.encode(
{"user_id": user_id, "exp": int(time.time()) + 3600},
secret,
algorithm=algorithm,
)
print(f"export {user_id.upper()}_TOKEN={token}")eval "$(python make_tokens.py)"Call the agent without a token, and the server answers 401:
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/v1/threadsCall it as Alice. This returns 200, and Alice now owns the new thread:
THREAD_ID=$(curl -s -X POST http://127.0.0.1:8000/v1/graph/invoke \
-H "Authorization: Bearer $ALICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":[{"type":"text","text":"Where is order 1042?"}]}]}' \
| python -c "import json,sys; print(json.load(sys.stdin)['data']['meta']['thread_id'])")Read Alice’s thread as Bob, and the server answers 404, as it does for a thread id that does not exist. Bob’s own thread list is empty:
curl -s -o /dev/null -w "%{http_code}\n" \
-H "Authorization: Bearer $BOB_TOKEN" \
http://127.0.0.1:8000/v1/threads/$THREAD_ID/messagesThe same request with $ALICE_TOKEN answers 200 with her messages. See Security in five minutes for what this one setting turned on and what it leaves to you.
Call it from TypeScript
The 10xGraph client for TypeScript wraps the HTTP API with types and helper methods. It requires Node.js 20 or newer. Install it:
npm install 10xgraph-clientCreate client.ts. It reads Alice’s token from the environment and prints the reply as it streams in:
import { TenxGraphClient, Message, StreamEventType, bearerAuth } from "10xgraph-client";
const client = new TenxGraphClient({
baseUrl: "http://127.0.0.1:8000",
auth: bearerAuth(process.env.ALICE_TOKEN ?? ""),
});
async function main() {
const stream = client.stream([Message.text_message("Where is order 1042?")]);
for await (const chunk of stream) {
if (chunk.event === StreamEventType.MESSAGE && chunk.message?.role === "assistant") {
process.stdout.write(chunk.message.text());
}
if (chunk.event === StreamEventType.ERROR) console.error(chunk.data);
}
console.log();
}
main();Run it in the shell where ALICE_TOKEN is exported, with a TypeScript runner such as tsx:
npx tsx client.tsUse client.invoke(messages, options) to get the whole result at once; result.meta.thread_id holds the thread id, and result.messages.at(-1)?.text() is the final reply. The client also exports basicAuth(username, password) and headerAuth(name, value) for other auth schemes. See Create a client.
Write the deploy files
The image installs what requirements.txt lists, and init already wrote that file with your provider extra and 10xgraph-api. It does not include the jwt extra, which the server needs once "auth": "jwt" is set, so add it. For the Google provider the file then reads:
10xgraph[google-genai]>=1.0,<2.0
10xgraph-api[jwt]>=1.0,<2.0Then generate the files:
10xgraph build --yesIt writes a Dockerfile and a .dockerignore. Add --docker-compose or --k8s for a docker-compose.yml or a k8s.yaml. The image runs Gunicorn in MODE=production, and .dockerignore leaves .env out, so pass the provider key and JWT_SECRET_KEY as environment variables when you run the container. The command also prints warnings that rate limiting and token revocation are off. See Deploy with Docker and Kubernetes for building, running and the release checklist.
Understanding the request and response
The fields you can send to /v1/graph/invoke and /v1/graph/stream, the fields in data, and the message format are listed in the graph endpoints reference. data.meta carries thread_id and is_new_thread.
Your first agent is running, secured and ready to ship. If 10xGraph saved you time, a star on GitHub helps other developers find it.
Next
Frequently asked questions
- Do I need ReactAgent, or should I write a StateGraph myself?
- Start with ReactAgent. The project that 10xgraph init writes uses it. It builds the standard reason-and-act graph for you (one agent node, one tool node, a conditional edge between them) and returns a normal compiled graph. Move to StateGraph when you need custom routing or several agents.
- Can I use OpenAI or Anthropic instead of Google?
- Yes. Pick the provider at the init question (or pass --provider), install the matching extra and put the provider key in .env. Init writes the matching model and provider lines into graph/agent.py. The tools, the graph and the API server stay the same.
- What does 10xgraph init create in Quick setup?
- Six files. 10xgraph.json tells the server where your graph is, graph/agent.py holds the agent, .env.example lists the provider key to set, requirements.txt lists the packages the Docker image installs, graph/__init__.py makes graph a package, and .gitignore keeps .env out of git.
- Which Node.js version does the TypeScript client need?
- Node.js 20 or newer. Install the client with npm and point TenxGraphClient at the baseUrl of your running 10xgraph dev server.
- How do I authenticate the TypeScript client?
- Pass an auth option to the TenxGraphClient constructor, for example bearerAuth(token), and read the token from an environment variable. The client also exports basicAuth(username, password) and headerAuth(name, value).
- Why does the second curl call remember the first one?
- Both calls send the same thread_id, and the compiled graph has a checkpointer. The checkpointer stores the conversation per thread, so the next call on that thread continues it.