Skip to main content
Agent commands let you create, list, spawn, chat with, and terminate agents in your AgentOS deployment.

​
agent new

Create a new agent from a template. 
agentos agent new [template]
​
template
string
Template name to use (defaults to “assistant”)

​
Available Templates

AgentOS includes 45+ pre-built agent templates:
  • coder - Full-stack coding agent
  • debugger - Debug and fix issues
  • architect - System design and architecture
  • code-reviewer - Code review and analysis
  • doc-writer - Documentation generation
  • test-engineer - Test creation and execution
  • devops-lead - DevOps and infrastructure
  • ai-engineer - AI/ML development
Example: 
agentos agent new coder
Output: 
✓ Created agent: agent-coder-1

​
agent list

List all active agents. 
agentos agent list
Example output: 
ID                   STATUS          NAME
default              active          Default Assistant
agent-coder-1        active          Code Agent
agent-researcher-2   active          Research Agent

​
agent chat

Start an interactive chat session with a specific agent. 
agentos agent chat <agent>
​
agent
string
required
Agent ID to chat with
Example: 
agentos agent chat agent-coder-1
Interactive session: 
→ Chatting with agent-coder-1. Type 'exit' to quit.

you> Write a function to validate email addresses

agent> I'll create an email validation function for you:

```javascript
function validateEmail(email) {
  const pattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return pattern.test(email);
}
This function uses a regex pattern to validate basic email format. you> exit 

<Tip>
  Use `agentos chat [agent]` as a shorthand for quick chat sessions.
</Tip>

## agent kill

Terminate a running agent.

```bash
agentos agent kill <agent>
​
agent
string
required
Agent ID to terminate
Example: 
agentos agent kill agent-coder-1
Output: 
✓ Agent agent-coder-1 terminated
Killing an agent terminates it immediately. Any ongoing operations will be stopped.

​
agent spawn

Spawn a new agent instance from a template. 
agentos agent spawn <template>
​
template
string
required
Template name to spawn from
Difference between new and spawn:
  • agent new - Create a new agent definition (can be customized before running)
  • agent spawn - Instantly create and start a new agent instance
Example: 
agentos agent spawn researcher
Output: 
✓ Spawned: agent-researcher-3

​
Quick Chat & Message

Two additional commands for interacting with agents:

​
chat

Shorthand for agent chat. 
agentos chat [agent]
​
agent
string
Agent ID (defaults to “default”)
Example: 
# Chat with default agent
agentos chat

# Chat with specific agent
agentos chat coder

​
message

Send a single message without starting an interactive session. 
agentos message <agent> <text> [--json]
​
agent
string
required
Agent ID to message
​
text
string
required
Message text
​
--json
boolean
Return response in JSON format
Example: 
agentos message coder "Explain the factory pattern"
Output: 
The factory pattern is a creational design pattern that provides
an interface for creating objects without specifying their exact class...
JSON output: 
agentos message coder "Explain the factory pattern" --json

{
  "agentId": "coder",
  "content": "The factory pattern is a creational design pattern...",
  "tokens": 245,
  "model": "claude-opus-4-6",
  "timestamp": "2026-03-09T10:30:00Z"
}

​
Agent Lifecycle

Typical agent workflow:

​
Examples

# Create and chat with a coder agent
agentos agent new coder
agentos agent chat agent-coder-1

​
Integration with Workflows

Agents can be invoked from workflows: 
{
  "steps": [
    {
      "type": "agent",
      "agentId": "researcher",
      "input": "Research topic: ${input.topic}"
    },
    {
      "type": "agent",
      "agentId": "writer",
      "input": "Write article based on: ${steps[0].output}"
    }
  ]
}
See Workflow Commands for more details.

​
Agent Configuration

Agents inherit configuration from:
  1. Global config (~/.agentos/config.toml)
  2. Agent-specific config (~/.agentos/agents/<agent-id>/config.toml)
  3. Runtime parameters
See Config Commands for configuration management.

​
Next Steps

Workflow Commands

Create workflows with multiple agents

Security Commands

Set up agent permissions and approvals

Config Commands

Configure agent behavior and models

Sessions

View and manage agent sessions

Build docs developers (and LLMs) love

Get started for freeTalk to us