Docs / Architecture / Agents

Agents

Ploton works with any AI agent framework — LangChain, CrewAI, custom builds. Here's how agents integrate.

Agent integration

Ploton is not an agent framework. It’s infrastructure that any agent can call.

Building with LangChain, CrewAI, AutoGPT, Semantic Kernel, or your own custom agent loop — doesn’t matter. If your agent can make an HTTP request, it can use Ploton. No adapter, no plugin system, no vendor lock-in. Your agent hits a REST API when it needs real-world capabilities, and Ploton handles the rest.

The agent-Ploton loop

The typical flow:

sequenceDiagram
    participant App as Your App
    participant Agent as Your Agent
    participant Ploton
    participant Service as External Service

    App->>Agent: Assign task
    Agent->>Agent: Reason about approach
    Agent->>Ploton: POST /v1/tasks (prompt)
    Ploton-->>Agent: 200 OK (task_id)
    Note over Agent: Continues other work
    Ploton->>Service: Auth, fetch, execute
    Service-->>Ploton: Response
    Ploton->>App: Webhook (task.complete)
    App->>Agent: Resume with result

In code:

// Inside your agent's tool handler
async function handleExternalDataRequest(agentContext: AgentContext) {
	// Agent calls Ploton when it needs external data
	const response = await fetch("https://api.ploton.ai/v1/tasks", {
		method: "POST",
		headers: {
			Authorization: `Bearer ${process.env.PLOTON_API_KEY}`,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({
			prompt: `Pull all active subscriptions for ${agentContext.userId}. Return plan name, amount, and next billing date.`,
			user_id: agentContext.userId,
			metadata: {
				agent_session: agentContext.sessionId,
				step: "fetch_subscription_data",
			},
		}),
	});

	const task = await response.json();

	// Agent continues — doesn't block on Ploton
	return {
		status: "delegated_to_ploton",
		task_id: task.id,
		message: "Subscription data request submitted. Will resume on webhook.",
	};
}

The metadata field is how you correlate Ploton results with your agent’s state. When the webhook comes back, use agent_session and step to resume the right agent at the right point.

Framework integration patterns

LangChain / LangGraph

Register Ploton as a tool in your agent’s toolset:

from langchain.tools import Tool

ploton_tool = Tool(
    name="ploton_external_action",
    description="Use this when you need to connect external services, fetch user data from third-party APIs, or handle authentication flows. Provide a clear description of what data you need and from which service.",
    func=call_ploton_api,
)

agent = initialize_agent(
    tools=[ploton_tool, ...other_tools],
    llm=llm,
)

The tool description is what tells the LLM when to reach for Ploton vs. other tools. Be specific about what Ploton handles: external services, OAuth, third-party data.

CrewAI

from crewai import Tool

ploton_tool = Tool(
    name="External Service Action",
    description="Delegates tasks to Ploton for external service interactions (APIs, OAuth, data fetching). Returns a task ID — results arrive via webhook.",
    func=call_ploton_api,
)

Custom agent loops

If you’re running your own agent loop, Ploton slots into the tool-use step:

while (!task.isComplete()) {
	const action = await agent.decide(task.context);

	if (action.type === "external_service") {
		// Delegate to Ploton
		const plotonTask = await createPlotonTask(action.prompt, task.userId);
		task.awaitCallback(plotonTask.id);
		continue; // Process next task in queue
	}

	if (action.type === "internal") {
		await executeInternally(action);
	}
}

Agent design considerations

When to call Ploton

Call Ploton when your agent needs to:

  • Authenticate with a third-party service — OAuth flows, token management, credential handling
  • Fetch data from external APIs — CRM records, payment data, calendar events, file storage
  • Take actions on external services — send emails, post messages, create records, upload files
  • Handle user interaction — collect approvals, preferences, or missing data

Don’t call Ploton for internal computations, reasoning, or queries against your own database. If it doesn’t touch an external service, you don’t need Ploton.

Keep prompts specific

Ploton’s output quality tracks directly with prompt quality. Vague prompts get vague results. See the Prompt Engineering guide for patterns that work.

Handle the async gap

Between creating a task and receiving the webhook, your agent needs a strategy:

  • Queue-based — agent enqueues tasks and processes results as they arrive. Best for high-throughput systems.
  • Polling fallback — agent periodically checks task status. Useful when webhooks aren’t available.
  • Hybrid — webhooks as primary delivery, polling as a fallback for missed events.

Use metadata for correlation

Include enough metadata to pick up where you left off when the result arrives:

{
	"metadata": {
		"agent_session_id": "sess_abc123",
		"workflow_step": "enrich_contact_data",
		"attempt": 1,
		"parent_task_id": "your_internal_task_id"
	}
}

Next steps

Previous Webhooks Next Authentication