Use Your AI Agent via CLI and HTTP Agent URL

Use Your AI Agent via CLI & Agent URL

Hey there,

Your Second Brain OS agent is configured and your tools are live. This guide covers the most flexible way to interact with your agent: a raw HTTP endpoint that accepts a message and returns a response. No MCP, no UI, no framework, no platform — just your agent over a HTTP API.

This is for developers, builders, and anyone who wants to integrate their AI agent into custom applications, scripts, or workflows. If you’re a business owner who isn’t technical, the other channel guides (website, voice, Telegram) are better starting points — but keep this in mind for when you hire a developer or want to connect your agent to something custom.

This is part of a Crash Course on Second Brain OS AI Agents. Access all the Automations to deploy your AI agent to 6 channels — website, voice, Telegram, ChatGPT, Claude & CLI — you get the full masterclass when you purchase ANY AI Agent by clicking the button below

Umair Kamil

Install Second Brain OS AI Agents

What You’ll Need

Your Second Brain OS account (setup completed from the main guide)
A terminal or any tool that can make HTTP requests (curl, Postman, a programming language, etc.)

Your Agent Endpoint

Go to secondbrainos.com/agent-url to get your user-specific curl command. It looks like this:

curl -X POST 'https://openai.secondbrainos.com/completion' 
  -H 'Authorization: Bearer recXXX:xxx-xxx-xxx' 
  -H 'Content-Type: application/json' 
  -d '{
    "channel": "webchat",
    "conversation_id": "conv_123",
    "session_id": "webchat_visitor_JaneDoe",
    "deliver_to_webhook": false,
    "message": "What slots are available tomorrow?"
  }'

That’s it. Send a POST request, get a response from your AI agent — with full access to all your public tools, knowledge, and skills.

Understanding the Parameters

Parameter	Type	Purpose
`channel`	string	Identifies where the message is coming from. This is a free-form field — not a fixed list. Use any value that makes sense for your integration: `webchat`, `whatsapp`, `instagram`, `sms`, `email`, `slack`, `mobile_app`, `internal_dashboard`, `crm_widget`, or anything else
`conversation_id`	string	The conversation_id from your CRM or custom application. For the latter, this can have the same value as session_id.
`session_id`	string	Groups messages into a thread and maintains context across messages. The AI agent remembers everything said within the same session. Use a stable, consistent id like `whatsapp_+15551234567_JohnDoe` or `web_visitor_abc123`
`deliver_to_webhook`	boolean	`false` = return the response in the HTTP response body. `true` = forward the response to your configured webhook URL instead. Useful when the requesting client times out and you want your messages to be delivered to a webhook for dispatching messages back to the original conversation_id/session_id.
`message`	string	The user’s message — whatever they’re asking or telling the agent

The channel field deserves special attention. It’s not an enum — you can pass any string. This is intentional. It lets you tag every interaction by source, which is useful for:

Analytics: “How many conversations came from WhatsApp vs Instagram vs my custom app?”
Routing: Your agent can behave differently based on the channel (if you configure it to in the system prompt)
Debugging: When reviewing logs, you can see exactly where each conversation originated

Session Persistence: The Key to Multi-Turn Conversations

The session_id is what makes this endpoint powerful. As long as you send the same session_id, the AI agent maintains full context of the conversation.

Example: A three-message booking flow

# Message 1: Ask about availability
curl -X POST 'https://openai.secondbrainos.com/completion' 
  -H 'Authorization: Bearer recXXX:xxx-xxx-xxx' 
  -H 'Content-Type: application/json' 
  -d '{
    "channel": "custom_app",
    "conversation_id": "conv_001",
    "session_id": "app_user_john_doe",
    "deliver_to_webhook": false,
    "message": "What times are available on Monday?"
  }'

# Message 2: Book a slot (agent remembers the context)
curl -X POST 'https://openai.secondbrainos.com/completion' 
  -H 'Authorization: Bearer recXXX:xxx-xxx-xxx' 
  -H 'Content-Type: application/json' 
  -d '{
    "channel": "custom_app",
    "conversation_id": "conv_001",
    "session_id": "app_user_john_doe",
    "deliver_to_webhook": false,
    "message": "Book me at 2:30pm. My name is John Doe, email john@example.com"
  }'

# Message 3: Reschedule (still in context)
curl -X POST 'https://openai.secondbrainos.com/completion' 
  -H 'Authorization: Bearer recXXX:xxx-xxx-xxx' 
  -H 'Content-Type: application/json' 
  -d '{
    "channel": "custom_app",
    "conversation_id": "conv_001",
    "session_id": "app_user_john_doe",
    "deliver_to_webhook": false,
    "message": "Actually, can you move that to 3:30pm instead?"
  }'

The agent remembers the availability it fetched, the booking it made, and the contact details — all within the same session. No need to repeat information.

Use Cases

1. Custom Chat UIs

Build your own chat interface in React, Vue, Swift, Flutter — anything that can make HTTP requests. The channel field tags each request by source:

# From your React web app
"channel": "react_webapp"

# From your mobile app  
"channel": "ios_app"

# From your internal admin dashboard
"channel": "admin_panel"

Your agent responds the same way regardless of the interface. The channel tag is for your analytics, not the agent’s behaviour (unless you configure channel-specific logic in the system prompt).

2. Agentic Workflows

Use the session_id to delegate multi-step tasks to your agent programmatically. A script can orchestrate complex workflows by sending sequential messages:

# Step 1: Research
"message": "Search my knowledge base for all clients who booked last month"

# Step 2: Analyse (same session — agent has the research results)
"message": "Which of those clients haven't rebooked yet?"

# Step 3: Act (still in context)
"message": "Send a follow-up email to each one with our availability for next week"

Each message builds on the previous context. The agent handles the tool calls (search, filter, email) automatically. You’re orchestrating the what, the agent handles the how.

If you’ve used Zapier or n8n: This is like chaining multiple Zap steps — except instead of pre-defining every step, you describe the goal and the AI figures out the steps. And if something unexpected happens mid-flow (e.g. a client already rebooked), the agent adapts instead of failing.

3. Cross-Platform Continuity

A customer starts a conversation on WhatsApp. Later, you pull up their session in your internal dashboard. Because you use the same session_id, the agent has full context:

# Customer's initial message (via WhatsApp webhook)
"channel": "whatsapp", "session_id": "whatsapp_+15551234567_JohnDoe"

# Your team reviews in the admin panel (same session)
"channel": "admin_panel", "session_id": "whatsapp_+15551234567_JohnDoe"

The agent knows everything the customer said on WhatsApp. Your team can continue the conversation, ask the agent for a summary, or take over — all with full context.

4. Batch Operations

Script bulk interactions for operational tasks:

# Process a list of leads
for lead in leads:
    curl ... -d '{"message": "Check availability and book '$lead' for the next open slot", "session_id": "batch_'$lead'"}'

Each lead gets its own session so conversations don’t bleed into each other.

5. Claude Code Integration

Use curl within Claude Code to interact with your SBOS agent as part of a development workflow:

# Inside Claude Code, test your agent's response to a specific scenario
curl -X POST 'https://openai.secondbrainos.com/completion' 
  -H 'Authorization: Bearer recXXX:xxx-xxx-xxx' 
  -H 'Content-Type: application/json' 
  -d '{"channel": "claude_code_test", "session_id": "test_001", "deliver_to_webhook": false, "message": "A customer wants to book two appointments on the same day for different services. Handle this."}'

This is useful for testing edge cases, simulating customer conversations, and validating your agent’s behaviour before deploying to customer-facing channels.

6. Webhook Delivery

Set deliver_to_webhook: true to have the agent’s response forwarded to your configured webhook URL instead of returned in the HTTP response. This is useful for:

Asynchronous processing (the agent might take a few seconds for complex tool calls)
Integrating with systems that expect push-based delivery (Slack bots, Discord bots, custom notification systems)
Building event-driven architectures where the agent’s response triggers downstream actions

Configure your webhook URL in your SBOS profile under notification settings.

Response Format

The endpoint returns a JSON response with the agent’s reply:

{
  "response": "I found 3 available slots on Monday: 10:00am, 2:30pm, and 4:00pm (Pakistan Standard Time). Which one works best for you?",
  "conversation_id": "conv_001",
  "response_id": "resp_0d823bd5d4e899bb0069e77b625d9c8191a4a2919ea22744aa",
  "usage": {
    "input": 1378,
    "output": 114
  }
}

Field	Purpose
`response`	The agent’s reply text
`conversation_id`	Echoes back your conversation ID for reference
`response_id`	A unique identifier for this specific response — useful for logging and debugging
`usage`	Token counts for the request (`input`) and response (`output`) — helps you track API costs

Security

Authentication: Every request requires your SBOS API key in the Authorization header. Requests without a valid key are rejected
Tool access: The agent can only use tools that are set to public in your SBOS account. Private tools are not accessible via this endpoint
Rate limiting: Standard rate limits apply. Contact support if you need higher throughput for batch operations
No credential exposure: Your external service credentials (Calendly tokens, CRM API keys, etc.) are stored server-side in SBOS and never appear in API responses

Troubleshooting

Issue	Fix
401 Unauthorized	Check your API key — it should be the full value including `Bearer` prefix
Agent doesn’t use tools	Verify tools are set to `public` in My Actions. The CLI endpoint only accesses public tools
Session context lost	Make sure you’re sending the same `session_id` across messages. Different session IDs = different conversations
Slow responses	Complex tool calls (booking, searching) take longer than simple Q&A. Consider using `deliver_to_webhook: true` for async delivery
Empty response	Check that your system prompt is configured in Profile → AI Agent Settings. An agent without a system prompt may produce minimal responses

Your AI agent is now accessible via HTTP. Whether you’re building a custom chat interface, scripting batch operations, orchestrating agentic workflows, or integrating with any system that can make HTTP requests — this endpoint is the foundation.

Next up: check out the other channel deployment guides:

Umair Kamil

Install Second Brain OS AI Agents