Talk to Your Agents

Send HTTP messages to your systemprompt agents and see them respond in real-time. Learn the CLI commands and HTTP endpoints for agent communication.

On this page

Your systemprompt template comes with a running agent. This guide shows you how to communicate with it using HTTP requests and CLI commands.

Prerequisites

  • Running systemprompt instance (just start completed)
  • Terminal access
  • Optional: curl or httpie for HTTP requests

Check Running Services

First, verify your agents are running:

# Check all services
systemprompt infra services status

# List available agents
systemprompt admin agents list

You should see the welcome agent running on port 9000.

Agent Endpoints

Each agent exposes several HTTP endpoints:

Endpoint Method Description
/api/v1/agents/{name} POST Send a message to the agent
/api/v1/agents/{name}/.well-known/agent.json GET Agent card (A2A metadata)
/api/v1/agents/{name}/tasks POST Create a task
/api/v1/agents/{name}/tasks/{id} GET Get task status

Send a Message

Using curl

curl -X POST http://localhost:8080/api/v1/agents/welcome \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "text": "Hello! What can you help me with?" }]
      }
    },
    "id": 1
  }'

# Send a message via CLI
systemprompt admin agents message welcome "Hello! What can you help me with?"

The CLI handles the JSON-RPC formatting and displays the response in a readable format.

Stream Responses

For real-time streaming responses, add the Accept: text/event-stream header:

curl -X POST http://localhost:8080/api/v1/agents/welcome \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "text": "Write me a short poem about programming" }]
      }
    },
    "id": 1
  }'

Streaming returns Server-Sent Events (SSE) with partial responses as they're generated.

View Agent Card

Get the A2A agent card with capabilities:

curl http://localhost:8080/api/v1/agents/welcome/.well-known/agent.json | jq

This returns:

  • Agent name and description
  • Available skills
  • Supported input/output modes
  • Authentication requirements

View Conversation Logs

Track agent conversations and performance:

# View recent AI requests
systemprompt infra logs request list --limit 10

# Audit a specific request
systemprompt infra logs audit <request-id> --full

# View agent-specific traces
systemprompt infra logs trace list --agent welcome --limit 10

Test Agent Skills

The welcome agent has these skills by default:

Skill Description
general_assistance Help with questions and explanations
content_writing Writing and editing text content

Target a specific skill by adding metadata:

curl -X POST http://localhost:8080/api/v1/agents/welcome \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "text": "Help me write a blog post introduction about AI agents" }]
      },
      "metadata": {
        "skill_id": "content_writing"
      }
    },
    "id": 1
  }'

Create Your Own Agent

To create a custom agent:

# Copy the welcome agent config
cp services/agents/welcome.yaml services/agents/my-assistant.yaml

# Edit the configuration
# Change: name, port (use 9001+), endpoint, system prompt

# Sync to database
systemprompt cloud sync local agents --direction to-db -y

# Restart services
systemprompt infra services restart --all

See the Agent Configuration documentation for full configuration options.

Troubleshooting

Agent not responding

# Check agent status
systemprompt admin agents show welcome

# Check service logs
systemprompt infra logs view --level error --since 1h

Authentication errors

For local development, agents accept anonymous requests by default. Check your agent configuration if you see 401 errors:

# services/agents/welcome.yaml
auth:
  required: false  # Set to true for production

Empty responses

Check that your AI provider is configured:

  1. Verify services/ai/config.yaml has a provider configured
  2. Ensure API keys are set: systemprompt admin secrets list
  3. Test AI connectivity: systemprompt admin ai test

Next Steps