Skip to Content

Creating Queries

Queries are how you interact with models, tools, agents and teams in Ark. A query sends input to any target, or set of targets, and receives a response. You can create queries using kubectl, the fark CLI, or the Ark Query API.

What is a Query?

A query is a request to execute a task using an agent, team, model, or tool. It contains:

  • Input: The prompt or question you want to ask
  • Target: Which agent, team, model, or tool should process the request
  • Output: The response from the target

Queries support overrides to dynamically inject headers when interacting with models and MCP servers.

User Messages

If a type is not specified, then the input of a query is a single user message:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: query-simple
spec:
  input: "What is the capital of France"
  target:
    type: agent
    name: sample-agent

Apply this sample query with:

# Create the 'sample agent' if you haven't already, then run the query.
kubectl apply -f samples/agents/sample-agent.yaml
kubectl apply -f samples/queries/query-simple.yaml

Check the result:

kubectl get query query-simple -o yaml

Conversations

For multi-turn conversations, use conversationId to maintain context across queries. The memory service manages conversation history automatically.

apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: conversation-followup
  namespace: default
spec:
  input: "What is the sum of all previous sums?"
  conversationId: "your-conversation-id-here"
  target:
    type: agent
    name: sample-agent

The conversationId is returned in status.conversationId after the first query completes. Pass it to subsequent queries to continue the conversation.

Using fark CLI

Query an agent directly:

fark agent weather-agent "What's the weather like in New York?"

Query a team:

fark team team-seq "Analyze this data and provide recommendations"

Query a tool directly:

fark tool get_weather '{"location": "New York"}'

Create a named query:

fark query my-query

Using the Query API

The Query API lets you interact with agents, teams, models, and tools via HTTP.

Explore the Ark APIs docs for complete endpoint documentation.

List Available Targets

See all available agents, teams, models, and tools:

curl http://ark-api.default.127.0.0.1.nip.io:8080/v1/agents/
curl http://ark-api.default.127.0.0.1.nip.io:8080/v1/models/
curl http://ark-api.default.127.0.0.1.nip.io:8080/v1/teams/
curl http://ark-api.default.127.0.0.1.nip.io:8080/v1/tools/

Query an Agent

curl -X POST http://ark-api.default.127.0.0.1.nip.io:8080/v1/queries/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather-query",
    "type": "user",
    "input": "What'\''s the weather like in New York?",
    "target": {"type": "agent", "name": "weather-agent"}
  }'

Response:

{
  "metadata": {"name": "weather-query", "namespace": "default"},
  "spec": {
    "type": "user",
    "input": "What's the weather like in New York?",
    "target": {"type": "agent", "name": "weather-agent"}
  },
  "status": {
    "phase": "done",
    "response": {
      "content": "The current weather in New York is 72°F with partly cloudy skies..."
    },
    "conversationId": "conv-abc123"
  }
}

Querying with Python

import requests
 
response = requests.post(
    "http://ark-api.default.127.0.0.1.nip.io:8080/v1/queries/",
    json={
        "name": "python-query",
        "type": "user",
        "input": "Find repositories about kubernetes",
        "target": {"type": "agent", "name": "github-repo-accessor"},
    }
)
 
query = response.json()
print(query["status"]["response"]["content"])

Query a Team

curl -X POST http://ark-api.default.127.0.0.1.nip.io:8080/v1/queries/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "team-query",
    "type": "user",
    "input": "Analyze customer feedback and suggest improvements",
    "target": {"type": "team", "name": "team-seq"}
  }'

Query a Tool

curl -X POST http://ark-api.default.127.0.0.1.nip.io:8080/v1/queries/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tool-query",
    "type": "user",
    "input": "{\"location\": \"New York\"}",
    "target": {"type": "tool", "name": "get_weather"}
  }'

Next Steps

Last updated on
Quickstart