How to Use
This is a short tutorial for using context agents. Hopefully by the end of it you see the fun simplicity of the framework. All of the prompts and responses in this tutorial were generated with qwen/qwen3.5-35b-a3b. This is a sweet spot model - not so small that it's very limited in understanding but not too large, so you can host this very efficiently on a huge range of hardware.
The screenshots in this tutorial use our web playground.
An Empty Playground
Open an empty playground by following the link to the playground. By default, we've added a system prompt - let's go ahead and delete that. Replace the SystemPrompt.md with something like: "Go and fetch https://openlibrary.org/dev/docs/api/authors - I'd like to use this api to understand the works of my favorite authors." Some callouts: this is barely a system prompt. We are more just pointing it to a resource. That's ok. Context agents build themselves in conversation with you. They create the tools they need and they feed on the context you give them. This nugget of an idea - this is the seed, let's make it grow.

Explore
With this little context, your agent is hungry. When we wrote this tutorial, at this step the agent made 22 tool calls and confirmed connectivity to multiple OpenLibrary APIs. Let's now help the agent query a little faster by asking: "Create some tools to save that you can use to query for authors and books more effectively and update the system prompt to make for faster querying." Now we have a new file "tools.js" where the agent has written a host of JavaScript functions to access the data it needs. Now on the next invocation it has shortcuts to use.

Add Even More Context
We want users to be able to explore by genre. Create a skill science_fiction/top.md which has some information on the best science fiction writers of all time using the scifi community on Reddit as a reference. Likewise create a romance/top.md using the books community on Reddit. Look now - our context agent has new skills specific to a genre, but if you look at the tool calls it tried, it may be tricking us.

Verify Access
Do a quick follow-up: "Were you actually able to review the Reddit sites?" All of the executed code and your files are in a secure sandbox. The agent only has access to the domains we give it access to. So these calls to Reddit were denied. This is an important security feature - the agent operates within defined boundaries.

Refine
Ask the agent: "Ok, update the system prompt to summarize your capabilities with a focus on detailed subject and edition information that you get from open library." This will detail out a capabilities document and we can simply copy and paste that now as our system prompt. The agent has now documented its own capabilities!

Read-Only Mode
Now let's toggle on "Read-Only" in the bottom right corner. This will prevent the agent from writing new files. It's done enough documentation and exploration - we want it to get to work! Try this prompt: "I am interested in a collector's edition of William Gibson books. Tell me about his most acclaimed works." Drill into the tool calls here and you can see more about how the agent searches, how it uses (or doesn't use) the tools. But this workflow is essentially how we use a context agent: work with the agent to build up its own context, rewrite the system prompt and capabilities, then lock it and have it operate!

Advanced Capabilities
What about MCP Servers?
An MCP server is just a set of APIs wrapped up with their documentation and input/output types. Context agents can use their JavaScript frameworks to access MCP servers. Add these two files to your directory:
The "get_tools" script which your agent can easily run will create a markdown document of all the tools available and the run_tools.js provides a simple JavaScript interface to run those tools. It is the same as directly connecting to it. If you think your server updated, just ask your context agent to refresh the tool availability.
Embedding CT Agents
If you have special requirements, you can embed CT Agents in a Python program. Install the context agent package and try something like this:
import asyncio
import os
from pathlib import Path
from context_agent.agent import AgentDeps, agent
async def with_custom_tools():
"""Example where agent creates its own tools."""
exec_dir = "/tmp/my-agent-workspace"
Path(exec_dir).mkdir(parents=True, exist_ok=True)
deps = AgentDeps(
exec_dir=exec_dir,
allowed_domains=["api.stlouisfed.org"], # For FRED API example
)
# Set API key via environment (agent can access CT_PY_* vars)
os.environ["CT_PY_FRED_API_KEY"] = "your-api-key-here"
# First turn: agent creates a tool
result1 = await agent.run(
"""
Write a tools.js file with a function called fetchGDP that:
1. Gets the CT_PY_FRED_API_KEY env var
2. Fetches GDP data from FRED API
3. Returns the last 5 observations
""",
deps=deps,
)
print("Tool created:", result1.output)
# Second turn: agent uses the tool it just created
result2 = await agent.run(
"Use the fetchGDP function to get the latest GDP data",
deps=deps,
message_history=result1.new_messages(),
)
print("Tool result:", result2.output)Context agents use Pydantic-AI, so you can call a context agent however you would call a Pydantic-AI agent.