Skip to main content
Section navigation

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 running agents. This guide shows you how to communicate with them 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

The template ships two agents: developer_agent (the default, admin scope, port 9101) and associate_agent (user scope, port 9102). Both are reachable through the API server on port 8080.

Agent Endpoints

The API server exposes these HTTP endpoints for agents:

Endpoint Method Description
/api/v1/agents/{name} POST A2A JSON-RPC endpoint (send messages, get tasks)
/.well-known/agent-card.json GET Agent card for the default agent
/.well-known/agent-cards GET List all agent cards
/.well-known/agent-cards/{name} GET Agent card for a specific agent

The /api/v1/agents/{name} endpoint speaks the A2A JSON-RPC protocol. Messages, task lookups, and cancellations are all JSON-RPC methods (SendMessage, GetTask, CancelTask, SendStreamingMessage) posted to the same URL. The endpoint requires a bearer token.

Get a Token

Agent endpoints are authenticated. Mint a local admin session token first:

TOKEN=$(systemprompt admin session login --token-only --profile local)

Send a Message

# Send a message via CLI
systemprompt admin agents message developer_agent \
  -m 'Hello! What can you help me with?' --blocking

The CLI handles authentication, the JSON-RPC formatting, and displays the response in a readable format. Add --stream for streaming mode or --json for the full task JSON.

Using curl

Every A2A message needs a messageId and a contextId:

curl -X POST http://localhost:8080/api/v1/agents/developer_agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "SendMessage",
    "params": {
      "message": {
        "role": "ROLE_USER",
        "parts": [{ "text": "Hello! What can you help me with?" }],
        "messageId": "'"$(uuidgen)"'",
        "contextId": "'"$(uuidgen)"'"
      }
    },
    "id": 1
  }'

Stream Responses

For real-time streaming responses, use the SendStreamingMessage method:

curl -X POST http://localhost:8080/api/v1/agents/developer_agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "SendStreamingMessage",
    "params": {
      "message": {
        "role": "ROLE_USER",
        "parts": [{ "text": "Write me a short poem about programming" }],
        "messageId": "'"$(uuidgen)"'",
        "contextId": "'"$(uuidgen)"'"
      }
    },
    "id": 1
  }'

Streaming returns Server-Sent Events (SSE) with partial responses as they're generated. Via the CLI: systemprompt admin agents message developer_agent -m '...' --stream.

View Agent Card

Get the A2A agent card with capabilities:

curl http://localhost:8080/.well-known/agent-cards/developer_agent | 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 developer_agent --limit 10

Agent Skills

Each agent declares its skills in its YAML config under metadata.skills. The developer_agent includes skills such as:

Skill Description
demonstrate_governance Walk through the governance pipeline
inspect_ai_requests Query the AI request audit trail
manage_services Start, stop, and inspect services
systemprompt_cli Drive the systemprompt CLI

List skill definitions with systemprompt core skills list, and see the Skills documentation for authoring your own.

Create Your Own Agent

To create a custom agent:

# Copy an existing agent config
cp services/agents/developer_agent.yaml services/agents/my-assistant.yaml

# Edit the configuration
# Change: name, port (use an unused port), endpoint, system prompt

# Register it in services/config/config.yaml under includes:
#   - ../agents/my-assistant.yaml

# Restart services (agent YAML is ingested at startup)
systemprompt infra services restart

See the Agent Configuration documentation for full configuration options.

Troubleshooting

Agent not responding

# Check agent status
systemprompt admin agents show developer_agent

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

Authentication errors

Agent endpoints require OAuth bearer tokens. Each agent declares its required scopes in its YAML:

# services/agents/developer_agent.yaml
oauth:
  required: true
  scopes:
    - admin
  audience: a2a

If you see 401 errors, mint a fresh token with systemprompt admin session login --token-only --profile local and check the agent's oauth.scopes against your token's scope.

Empty responses

Check that your AI provider is configured:

  1. Verify a provider is enabled: systemprompt admin config provider list
  2. Ensure API keys are set: systemprompt admin config secret set
  3. Check recent request errors: systemprompt infra logs request list --limit 10

Next Steps