Create, configure, and deploy agents — from a simple chatbot to a fully autonomous worker.

Building Agents

Agents are defined by their instructions, model, and tools. This guide covers every configuration option.

Create your first agent

Go to Studio → Create Agent and fill in the form. The only required fields are Name and Instructions.

Model configuration

Supported providers and models

Provider	Key	Popular models
OpenAI	`openai`	`gpt-4o`, `gpt-4o-mini`, `o1-mini`
Anthropic	`anthropic`	`claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001`
Google	`google`	`gemini-1.5-pro`, `gemini-2.0-flash`
Groq	`groq`	`llama-3.3-70b-versatile`, `mixtral-8x7b-32768`
Mistral	`mistral`	`mistral-large-latest`, `mistral-small-latest`
Ollama	`ollama`	Any locally running model

Parameters

Parameter	Default	Description
`temperature`	`0.7`	Creativity. `0` = focused, `1` = creative
`maxTokens`	`2048`	Maximum response length
`topP`	`1.0`	Nucleus sampling
`frequencyPenalty`	`0`	Reduce repetition
`presencePenalty`	`0`	Encourage new topics

Bring your own key (BYOK)

Add a personal API key to use your own quota:

{
  "modelProvider": "anthropic",
  "modelId": "claude-sonnet-4-6",
  "apiKey": "sk-ant-your-key"
}

Your key is stored encrypted and used only for this agent's calls.

Self-hosted Ollama

{
  "modelProvider": "ollama",
  "modelId": "llama3.2",
  "baseUrl": "http://localhost:11434"
}

Writing effective instructions

Instructions are the agent's system prompt. Be specific — vague instructions produce vague agents.

Define the role and context clearly:

You are a financial analyst assistant for hedge fund managers.
You have access to real-time market data tools.
Always cite sources and provide confidence levels.

Specify the output format:

Always respond in this format:
1. Brief answer (1–2 sentences)
2. Supporting detail (bullet points)
3. Caveats if any

Set boundaries:

You only answer questions about cooking.
For off-topic questions, politely redirect back to culinary topics.

The persona field is separate from instructions. Use it for tone and character — "Analytical and direct" or "Friendly and patient" — so it doesn't clutter your functional instructions.

Knowledge base

The knowledge base injects static content the agent always has available — no tool call needed. Good for FAQs, product specs, or internal policies.

Studio → Agent Editor → Knowledge Base → Add item

Adding tools

Tools give agents capabilities beyond their training data.

Enable built-in tools:

{
  "commonTools": ["web_scraper", "search", "api_caller", "code_interpreter"]
}

Link a custom tool to an agent:

curl -X POST https://api.agentcommons.io/v1/agents/agent_abc123/tools \
  -H "x-api-key: YOUR_KEY" \
  -d '{ "toolId": "tool_xyz" }'

See Tools & MCP for how to create custom tools and connect MCP servers.

Autonomous mode

Autonomous mode runs the agent on a schedule — like a cron job for your agent. Each run, the agent wakes up, does its work, and sleeps until next time.

Studio → Agent Editor → Autonomy → Toggle on → Set interval or cron

For more control over scheduling — including one-time runs and task dependencies — use the Tasks system instead.

OAuth connections

Connect your agent to external services (Google, GitHub, Slack, etc.) so it can act on your behalf:

In Studio → Agent Editor → Connections, click Add Connection

Choose a provider (e.g. Google) and complete the OAuth flow

The token is stored and injected automatically when the agent uses that provider's tools

Text-to-speech

Enable voice output for your agent:

{
  "ttsProvider": "openai",
  "ttsVoiceId": "alloy"
}

List available voices:

GET /v1/agents/tts/voices

Monitoring

What	How
Live logs	`GET /v1/logs/agents/:agentId`
Usage stats	`GET /v1/usage/agents/:agentId`
Session history	`GET /v1/agents/sessions/:sessionId/chat`
UI view	Studio → Tasks (for autonomous runs)

Building Agents

On this page